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NetBIOS Final Return Codes 

OOh Successful completion, good return 

01 h Invalid buffer length 

03h Invalid command 

05h Command timed-out 

06h Incomplete received message 

07h Local No-Ack command failed 

08h Invalid local session number 

09h No resource available 

OAh Session has been closed 

OBh Command was canceled 

ODh Duplicate name in local NetBIOS name table 

OEh NetBIOS name table full 

OFh Name has active sessions and is now deregistered 

11 h NetBIOS local session table full 

12h Session open rejected because no Listen is outstanding 

13h Illegal name number 

I4h Cannot find name called or no answer 

15h Name not found, or cannot specify asterisk (*) or OOh as first byte of NcbName, 

or the name is deregistered and cannot be used 
l6h Name in use on remote adapter 

17h Name deleted 

18h Session ended abnormally 

19h Name conflict detected 

lAh Incompatible remote device (PC Network) 

21 h Interface busy 

22h Too many commands outstanding 

23h Invalid number in NcbLanaNum field 

24h Command completed while gancel occurring 

25h Reserved name specified for Add Group Name 

26h Command not valid to cancel 

30h Name defined by another process (OS/2 Extended Edition only) 

34h NetBIOS environment not defined (OS/2 Extended Edition only) 

35h Required operating system resources (OS/2 Extended Edition only) 

36h Maximum applications exceeded (OS/2 Extended Edition only) 

37h No SAPs available for NetBIOS (OS/2 Extended Edition only) 

38h Requested resources not available (OS/2 Extended Edition only) 

40h System error (PC Network) 

41 h Hot carrier from a remote adapter detected (PC Network) 

42h Hot carrier from this adapter detected (PC Network) 

43h No carrier detected (PC Network) 

4Eh Status bit 12, 14, or 15 on longer than one minute (Token-Ring) 

4Fh One or more of status bits 8-11 on (Token-Ring) 

50h-F6h Adapter malfunction 

F7h Error on implicit DIR.INITIALIZE 

F8h Error on implicit DIR.OPEN.ADAPTER 

F9h IBM LAN Support Program internal error 

FAh Adapter check 

FBh NetBIOS program not loaded in PC 

FCh DIR.OPEN.ADAPTER or DLC. OPEN. SAP failed— check parameters 

FDh Unexpected adapter close 

FFh Command-pending status 
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Foreword 


NetBIOS is an extremely important network programming interface. In 
the PC-DOS arena NetBIOS provides a consistent interface for communi- 
cation systems using IBM, XNS, TCP, IEEE and OSI protocols, among 
others. As we networkers migrate our systems to new protocols such as 
OSI, to new LAN operating systems such as the OS/2 LAN Manager, and 
to new hardware platforms such as the PS/2 and Macintosh II, NetBIOS’s 
importance expands. 

Schwaderer’s C Programmer's Guide to NetBIOS gives clarity and 
stability to a heretofore illusory de facto standard. It provides historical 
perspective as well as a working NetBIOS reference. It illustrates princi- 
ples and techniques for developing the growing variety of NetBIOS ap- 
plications that operate on the many evolving LAN systems. 

Dr. Robert M. Metcalfe 
Ethernet Inventor 
Founder, 3Com Corporation 




Preface 


Network Basic Input/Output System (NetBIOS) is nearly a communica- 
tion programmer’s dream come true. Is NetBIOS perfect? I doubt it, but 
it takes so little effort to master and provides such a remarkably powerful 
LAN communications programming platform that I feel compelled to 
share it with the uninitiated — its innate simplicity as well as some of its 
more obscure areas. 

With the information in this book, you will learn 

• a history of NetBIOS and how it interrelates with other IBM hard- 
ware and software 

• name, datagram, and session support programming 

• the Neb fields 

• LAN data security and integrity 

• CRC fundamentals 

• NetBIOS commands 

Example listings throughout the book demonstrate application prin- 
ciples and the Appendixes provide ready reference tables and programs. 

Acknowledgments 

Two friends are mentioned in the dedication. The first, Jim Brady, is cur- 
rently my second-level manager. I am especially indebted to him for as- 
signing me to LAN-related projects for most of the two and one-half years 
I have worked in IBM’s disk-drive division. My assignments allow me to 
keep abreast of developments in LAN technology in a way that is presum- 
ably useful to our division. Thankfully, Jim has not wandered too far into 
communication subjects, or my life at work would be doubly difficult. 
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The second fellow is Larry Raper. He occasionally calls me at mid- 
night to suggest an approach for a program 1 am working on. This is re- 
markable because midnight in San Jose means Larry is calling at 3:00 
A. M. from the east coast. The sample C Post Routine in Appendix B 
is a direct consequence of one of these calls. Larry is one of the most 
brilliant programming craftsmen and system designers in the industry. 
Simply put, there are some as good, but none better anywhere. The in- 
ternal clarity, design elegance, and concussion of Larry’s programs can 
reduce even the most gifted programmers to despondency. 

I am most grateful that the paths of these two fellows have crossed 
mine to change it immeasurably for the better. In the event that you 
know or come to know them, you might not want to mention this tribute 
to them as they would likely immolate in crimson distress. It can be a 
secret we share. 

Finally, my deepest thanks to Nancy Albright for her remarkable edit- 
ing skills, to Jim Rounds and Marj Colvin for their coordinating efforts, to 
Ned Shaw for his spectacular cover, and to my acquisition editor, Jim Hill. 
His personal integrity is the principal reason I initially signed with How- 
ard W. Sams, and my regard for him has yet to change. 

This book was written on an IBM PC-AT using Wordproof and 
the Personal Editor 11. The programs were compiled using the Microsoft 
C 5.0 compiler and were debugged using the compiler’s CodeView de- 
bugger assisted by an Atron Miniprobe. 

Good luck with NetBIOS and drop a line if you will. I’d love to hear 
your thoughts on what might have been done better in this book or how 
you are using NetBIOS to improve your work. If you find any errors or 
have any suggestions, please write me in care of the publisher. 1 will do 
everything 1 can to personally reply and fix the problem in the next print- 
ing. Thanks in advance. 


W. David Schwaderer 
San Jose, California 
August 1988 
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Chapter 1 


Overview 


The Network Basic Input/Output System (NetBIOS) is an application 
programming interface for data exchange between data sources and data 
sinks. Loosely speaking, NetBIOS is a programming gateway to sets of 
services that allow computer applications and devices to communicate. 
Application programs must generally invoke these various NetBIOS serv- 
ices using specific command sequences. Hence, NetBIOS has explicit, 
though minimal, protocols associated with some of its services. 

Typically data exchange occurs between NetBIOS applications resid- 
ing within separate machines connected by a Local Area Network (LAN). 
However, two applications within the same machine can also use Net- 
BIOS for data communication without a LAN. Thus, though all IBM Net- 
BIOS implementations require a LAN adapter, NetBIOS use is not 
restricted to LAN environments. 


Where Does NetBIOS Fit in the Scheme of Things? 

If you are familiar with data communication theory, you might recall the 
International Standards Organization (ISO) Open Systems Interconnec- 
tion (OSI) Reference Model depicted in Figure 1-1. This conceptual 
model divides the various activities, typically required to effect orderly 
data communication between two applications residing in distinct ma- 
chines, into seven discrete processes or “layers.” NetBIOS’s location 
within this conceptual model is also illustrated in Figure Tl. 

During application-to-application communication, each layer within 
a given machine directly coordinates message-passing activities with the 
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. Peer ^ 

Layers 


Computer 1 Computer 2 



adjacent layers immediately above and below it. This type of communi- 
cation is called adjacent-layer communication. In addition, each layer 
within a machine also indirectly coordinates its message-passing activi- 
ties with its peer- level counterpart within the other machine. This type 
of communication is called peer-layer communication. 

NetBIOS is situated high within the reference model hierarchy, so ap- 
plications that program to the NetBIOS interface are largely isolated and 
essentially insulated from the precise way the lower layers interact with 
their peer and adjacent layers. For example, two NetBIOS applications 
may communicate using IBM PC Network adapters. The underlying 
communication may be accomplished using the native Session Manage- 
ment Protocol (SMP) located on the adapter card. The applications may 
also use the IBM PC LAN Support Program which uses IEEE 802.2 Logi- 



Chapter 1: Overview 


5 


cal Link Control (LLC) protocols. In any event, the application programs 
are insulated from the precise protocols used. 

This immunity allows general NetBIOS application portability across a 
spectrum of communication environments, though the portability is usu- 
ally not total. For example, each type of IBM LAN has a specific NetBIOS 
implementation, or will have according to one of IBM’s statements of direc- 
tion issued at the introduction of the IBM PC Network. Because of the vari- 
ety of IBM’s LAN offerings, the precise effect of some NetBIOS commands 
does vary by LAN offering and the same is generally true for other NetBIOS 
implementations within other communication environments. However, 
because of the significant portability of NetBIOS applications and Net- 
BIOS’s intuitive simplicity, NetBIOS has rapidly become an uncontested de 
facto industry standard. Moreover, while not a perfect fit, NetBIOS inter- 
faces are also appearing for other communication environments such as 
the popular TCP/IP and emerging MAP /TOP environments. 

NetBIOS is rapidly becoming a pervasive data communication pro- 
gramming platform within a variety of operating environments such as 
PC-DOS, OS/2, and UNIX. Thus, if you are facile with NetBIOS program- 
ming, you possess a very marketable skill within an exploding market. 


Where Did NetBIOS Come From? 

NetBIOS first appeared in August 1984 with the IBM PC Network adapter 
card designed for IBM by Sytek Inc. The IBM PC Network was IBM’s first 
LAN. It provides a 2 -megabit per second data transmission burst rate 
across a broadband coaxial cable, using the popular industry standard 
Carrier Sense Multiple Access Carrier Detect (CSMA/CD) access method 
that first appeared with IEEE 802.3 Ethernet. 

Located on the IBM PC Network LAN Adapter (LANA) is an extended 
BIOS ROM referred to as the LANA’s Network Adapter BIOS. This ROM 
module occupies 8K bytes of memory, starting at memory segment 
CCOOh, and contains the LANA initialization routines, diagnostics, 
coprocessor and PC memory interface routines, and part of the first Net- 
BIOS implementation. The remainder of this implementation is located 
on a second adapter ROM referred to as the adapter’s protocol ROM. The 
adapter ROM also contains routines that allow a medialess (no bootable 
hard disk or available diskette) IBM PC to boot from a boot-server con- 
nected to the same network. The surrogate diskette boot process is re- 
ferred to as Remote Program Load (RPL) and invokes the coresident ROM 
NetBIOS services to achieve its purpose. 
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What Is “Tlpue NetBIOS ”? 

The industry standard TCP/IP NetBIOS implementations, first demon- 
strated in December 1987, required NetBIOS extensions for resolution of 
internetwork routing between, and name resolution within, intercon- 
nected network environments. Because the MAP/TOP implementations 
are in their embryonic stages as of this writing, differences are likely to 
appear there as well. 

Within the IBM product line, the current version of the IBM LAN 
Support Program provides the “true NetBIOS” implementation because 
it provides NetBIOS support for all of IBM’s LAN adapters through a vari- 
ety of PC-DOS device drivers. 

One significant advantage of this program is that it allows IBM’s vari- 
ous adapters to communicate with each other via an intermediary PC or 
PS/2’* running the IBM Token-Ring/PC Network Interconnect Program. 
This enables IBM PC Network LAN workstations to communicate with 
Token-Ring based workstations, among other things. Thus, strategic rea- 
sons alone dictate that the IBM LAN Support Program’s NetBIOS imple- 
mentation supersede the original implementation as the true NetBIOS 
industry standard. 


How Do I Get NetBIOS? 

If you are using an IBM LAN, the answer to this question requires a histor- 
ical product survey, which follows. Otherwise, consult your system ven- 
dor. 


Original PC Network LANA Card 

NetBIOS is automatically included on each IBM PC Network Adapter 
LANA card. However, because the LANA ROM is a PC BIOS extension, it, 
like the PC-XT Fixed Disk Adapter, Extended Graphics Adapter (EGA), 
etc., requires the presence of the PC BIOS Extended BIOS Option. This 
feature is automatically included with every IBM PC model except the 
original IBM PC (i.e., is available with the IBM PC-XT, IBM PC-AT, etc.). 
In the case of the original IBM PC, this requires a BIOS-ROM upgrade 


*PC includes the IBM PC family (excluding the PC Junior) and the PS/2 family, unless 
explicitly stated otherwise. 
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before the NetBIOS is usable. The effect of the upgrade is that after exe- 
cuting its Power-On-Self- Tests (POST) and initialization routines — but 
before loading PC-DOS — the PC scans PC memory for BIOS extensions. 
The BIOS starts at memory location C800:0000 and looks for the ex- 
tended ROM signature value of AA55h every 2K bytes. Because IBM no 
longer provides BIOS ROM upgrade kits, check with your systems sup- 
plier for alternate ways to install this capability. 

If the AA55h value is found, a BIOS extension is detected and exe- 
cuted by calling the instruction three bytes beyond the AA55h value. 
This permits the ROM extension to perform various activities, such as 
adapter and interrupt vector initialization. When complete, each ROM 
extension returns to the PC BIOS, allowing the PC BIOS to continue its 
memory scan for more ROM extensions. Hence, individual or multiple 
BIOS extensions initialize in an orderly manner. 

Subsequent to the availability of the first LANA NetBIOS, IBM up- 
graded the Network Adapter BIOS with another version of the ROM. If 
you have a LANA adapter, you can determine whether you have the ini- 
tial NetBIOS ROM or the upgraded one. Using PC-DOS’s DEBUG.COM 
program, you can display the value at memory location CCOOrOOOO. Near 
that location you see the Network Adapter BIOS part number, which is 
either 6360715 for the original version or 6480417 for the upgraded ver- 
sion. 

You can also visually inspect the actual LANA NetBIOS chip, which is 
positioned in an upside-down orientation on the lower edge of the card 
immediately above the lefthand side of the adapter’s PC bus connector. 
Figure 1-2 illustrates the position of the ROM chip. 

The original ROM’s copyright date has the year 1984 and the updated 
version, 1985. These dates are also displayed in memory near the Net- 
work Adapter BIOS part number. 



Fig. 1-2. Location of the PC Network LANA NetBIOS ROM chip. 
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NETBIOS.COM 

NETBIOS.COM is a complete NetBIOS replacement for the PC Network 
LANA NetBIOS. It is included with versions of the IBM PC LAN Program. 
Unlike the NetBIOS ROM version, NETBIOS.COM occupies memory 
within the 640K PC memory address space. When the IBM PC LAN Pro- 
gram executes, and when the adapter’s NetBIOS ROM has an earlier date 
than the NETBIOS.COM module, the IBM PC LAN Program automati- 
cally loads and executes NETBIOS.COM as part of its initialization pro- 
cess. This completely replaces the ROM’s NetBIOS services, upgrading 
the NetBIOS ROM. 

Note that NETBIOS.COM can be executed as part of an AUTOEXEC. 
BAT initialization procedure (or AUTOUSER.BAT in instances where the 
IBM PC LAN Program has usurped AUTOEXEC.BAT) if you wish to use 
NetBIOS prior to running your licensed copy of the IBM PC LAN Pro- 
gram. 

In the event you have the original NetBIOS and do not have an au- 
thorized copy ofNETBIOS.COM, contact your authorized IBM sales rep- 
resentative for replacement policy information. 


The IBM Token-Ring’s NETBEUI 

When IBM introduced the IBM Token-Ring in October 1985, it provided 
it with a NetBIOS programming interface. The NetBIOS support ap- 
peared as a separately purchased module named NETBEUI. COM, which 
is an acronym for NetBIOS Extended User Interface. 

NETBEUI.COM requires another module named TOKREUI.COM 
(Token-Ring Extended User Interface). TOKREUI.COM is included on 
the Token Ring Guide To Operations Diskette and provides another com- 
munication programming interface known as Data Link Control (DLC), 
which uses a different set of communication protocols than LLC. 
NETBEUI. COM translates NetBIOS commands into DLC commands and 
presents them to the DLC interface. The Token-Ring’s Technical Refer- 
ence Manual documents NETBEUI. COM’s services, which have minor 
deviations from the IBM LANA NetBIOS services. 


The IBM LAN Support Program 

IBM’s latest implementation of NetBIOS is an IBM LAN Support Program 
component named DXMTOMOD.SYS which works in conjunction with 
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other Program modules. All DLC and NetBIOS support is provided by 
combinations of members within the Program’s PC-DOS device drivers 
families. The specific device drivers you select depend on your particu- 
lar PC and optional software. DXMTOMOD.SYS can have 26 parameters 
which customize the installation of the Program. 


What IBM NetBIOS Reference Material Is Available? 

The PC Network Technical Reference Manual, the Token-Ring Network 
PC Adapter Technical Reference Manual, and the IBM NetBIOS Applica- 
tion Development Guide provide documentation and assistance in appli- 
cation and implementation of NetBIOS. 


PC Network Technical Reference Manual 

The PC Network Technical Reference Manual (IBM Part Number 
6322505 ) documents the original PC Network LANA NetBIOS program- 
ming interface and includes a Network Adapter BIOS listing in Appendix 
D. However, the LANA protocol ROM largely implements the actual Net- 
BIOS and no LANA protocol ROM listing is provided. Using PC-DOS DE- 
BUG. COM to examine the code shipped on the first version of the 
Network Adapter BIOS, and comparing it to the code in the listing, 
quickly reveals that the two are not identical. On page D-17, the listing 
mentions two PC-DOS include files that are not listed in the manual. One 
of them, NetBIOS. LIB, is present on the IBM PC Network Sample Pro- 
gram Diskette accompanying the Manual. The other, LANAS. INC, is un- 
documented. 

For these and other reasons, the Manual has limited utility in provid- 
ing an example NetBIOS implementation, although it has important RPL 
information as well as RPL sample program listings on the Diskette. Curi- 
ously enough though, the 1984 LANA NetBIOS code listing compares 
the BIOS model signature byte to an FCh constant (for a PC-AT) and asks 
the question “On a PC-3?” as a comment. 


Token-Ring Network PC Adapter Technical Reference Manual 

Chapter 5 of the Token-Ring Network PC Adapter Technical Reference 
Manual (IBM Part Number 69X7830) documents the NETBEUI.COM 
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programming interface, which varies slightly from the original PC Net- 
work LANA NetBIOS programming interface. Specifically, two additional 
commands are provided, as well as additional return codes, use of a pre- 
viously reserved area, and different status information reflecting the dif- 
ferences between a CSMA/CD and Token- Ring environment. The Sample 
Diskette contains some of the same program listings as the PC Network 
Technical Reference Manual Sample Diskette. 


IBM NetBIOS Application Development Guide 

The IBM NetBIOS Application Development Guide (IBM Part Number 
S68X-2270) describes the NetBIOS programming interface and provides 
pseudocode for the NetBIOS commands as well as the NetBIOS com- 
mands used with the PC Network Protocol Driver Program. The PC Net- 
work Protocol Driver Program allows PC Network II and PC Network 
II/A adapters to communicate with the original PC Network LANA 
adapter cards using the original LANA protocols. 


DXMINFO.DOC 

The IBM LAN Support Program device drivers are provided on a PC disk- 
ette along with a printable file named DXMINFO.DOC. This file contains 
several pages of critical late-breaking NetBIOS and adapter configuration 
information. It also documents the 26 DXMTOMOD.SYS NetBIOS input 
parameters (discussed in Chapter 5). Be warned the information has a 
definite LLC terminology orientation. 

NetBIOS is a pervasive communications programming interface 
available within a variety of operational environments. Its several imple- 
mentations vary in minor ways, reflecting differences within specific 
communication environments. Because of its innate simplicity and intu- 
itive approach, NetBIOS has become an uncontested industry de facto 
standard. For the sake of simplicity, this book only discusses IBM’s PC 
LANs, though the discussion is generally extendable to numerous other 
environments. 



Chapter 2 


NetBIOS and IBM’s LAN Adapters 


IBM offers a variety of PC LAN adapters spanning five LAN environ- 
ments; 

• Token-Ring 

• PC Network Broadband 

• PC Network Baseband 

• Ethernet 

• the IBM Industrial Network 

IBM currently provides a NetBIOS implementation for each of these 
offerings except the Industrial Network and issued an August 1984 state- 
ment of direction that it would provide a NetBIOS interface for an “IBM 
Industrial local area network using the token-bus protocol.” 

The following hardware discussion is brief and illustrates the wide 
spectrum of IBM LAN adapter offerings. For a more detailed discussion 
of the individual adapters and the LAN technologies involved, consult 
IBM’s Local Area Networks: Power Networking and Systems Connectiv- 
ity (Schwaderer 1988). 


Token-Ring Environment 

IBM’s strategic LAN, the Token-Ring, provides a 4-megabit burst trans- 
mission rate on shielded and unshielded twisted-pair wiring using a to- 
ken access method within a ring topology. All IBM Token-Ring adapters 
transmit data signals on shielded twisted-pair copper wire using electri- 
cal voltage-level variations. 


II 
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IBM has also announced work on a l6-megabit shielded twisted-pair 
version, as well as a 100-megabit fiber optic Token-Ring based on the 
ANSI X3T9.5 Fiber Distributed Data Interface (FDDI) draft standard. 

Currently, IBM provides five Token-Ring Adapters: 

• IBM Token-Ring Network PC Adapter 

• IBM Token-Ring Network PC Adapter II 

• IBM Token-Ring Network Adapter/A 

• IBM Token-Ring Network Trace and Performance Adapter II 

• IBM Token-Ring Network Trace and Performance Adapter/A 

The IBM Token-Ring Network PC Adapter operates in IBM PCs, PC- 
XTs, PC-ATs, and PS/2 models 25 and 30, and contains 8K bytes of on- 
board shared-RAM for network functions and an empty socket which al- 
lows installation of an 8K-byte RPL feature EPROM. 

The 8K bytes are referred to as shared-RAM because both the PC’s 
microprocessor and the LAN adapter’s microprocessor directly access 
this memory. The RPL EPROM feature’s protocols are LLC-based. Hence, 
they are incompatible with the PC Network LANA RPL protocols that are 
NetBIOS/SMP-based. However, they are compatible with the onboard 
RPL capability of the IBM PC Network Broadband Adapter II(/A) adapters 
and the IBM PC Network Baseband Adapter(/A) adapters. 

The IBM Token-Ring Network PC Adapter II also operates in IBM PCs, 
PC-XTs, PC-ATs, and PS/2 models 25 and 30, and contains 16K bytes of 
onboard shared-RAM for network functions as well as an empty socket 
for an 8K-byte RPL feature EPROM. 

The additional 8K bytes of shared-RAM on the Adapter II allows it to 
use larger size transmission packets (essentially 2K bytes versus 1 K bytes) 
than the Adapter 1. Therefore, in high-transmission rate applications typi- 
cal for file servers, bridges, and gateways, the Adapter II has a significant 
performance advantage over the Adapter I. 

The IBM Token-Ring Network Adapter/A operates in all IBM PS/2s ex- 
cept PS/2 models 25 and 30, and contains 16K bytes of shared-RAM for 
improved network performance as well as an empty socket for an 8K- 
byte LLC-protocol RPL feature EPROM. 

The IBM Token-Ring Network Trace and Performance Adapter II op- 
erates in members of the original PC, PC-XT, PC-AT, and PS/2 models 25 
and 30, and with the IBM Token-Ring Network Trace and Performance 
Program. It also functions as a normal network adapter. 

The IBM Token-Ring Network Trace and Performance Adapter/A op- 
erates in members of the PS/2 except models 25 and 30, and with the 
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IBM Token-Ring Network Trace and Performance Program. It also func- 
tions as a normal network adapter. 


IBM PC Network Broadband Environment 

The IBM PC Network provides a 2-megabit burst rate on broadband ca- 
bling using the popular industry-standard IEEE 802.3 CSMA/CD access 
method within a branching-tree topology. IBM PC Network broadband 
adapters transmit data signals on coaxial cable using radio frequency (RE) 
techniques. Currently, IBM provides three PC Network broadband 
adapters, though two of them can operate at different frequencies by 
changing their adapter transceiver (RE modem): 

• IBM PC Network Adapter 

• IBM PC Network Adapter II 

• IBM PC Network Adapter II/A 

The IBM PC Network Adapter was discussed in Chapter I. The IBM 
PC Network Adapter II operates in IBM PCs, PC-XTs, PC-ATs, and PS/2 
models 25 and 30, and contains 8K bytes of shared-RAM for network 
functions. 

The IBM PC Network Adapter II/A operates in all IBM PS/2s except 
models 25 and 30, and contains 8K bytes of shared-RAM for network 
functions. 

Both the Adapter II and the Adapter II/A are available with transceiv- 
ers that operate at one of three different frequencies. Table 2-1 illustrates 
the relationships. 


Table 2-1. IBM PC Network Adapter II and Adapter II/A 
Frequency Options 


Broadband 

Channels 

IBM PC Adapter 

IBM PS/2 Adapter 

Chan. T14 &J 

IBM PC Network Adapter II 

IBM PC Network Adapter II/A 

Chan. 2’ & 0 

IBM PC Network Adapter II 

IBM PC Network Adapter II/A 


Frequency 2 

Frequency 2 

Chan. 3’ & P 

IBM PC Network Adapter II 

IBM PC Network Adapter II/A 


Frequency 3 

Frequency 3 
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IBM PC Network Baseband Environment 

The IBM PC Network Baseband provides 2-megabit burst transmission 
rates on twisted-pair wiring using the popular industry-standard IEEE 
802.3 CSMA/CD access method within star and single-bus topologies. 
Currently, IBM provides two PC Network baseband adapters: 

• IBM PC Network Baseband Adapter 

• IBM PC Network Baseband Adapter/A 

The IBM PC Network Baseband Adapter operates in IBM PCs, PC- 
XTs, PC-ATs, and PS/2 models 25 and 30, and contains 8K bytes of 
shared-RAM for network functions. 

The IBM PC Network Baseband Adapter/A operates in all IBM PS/2s 
except PS/2 models 25 and 30, and contains 8K bytes of shared-RAM for 
network functions. 

The individual members of the IBM PC Network baseband family of 
adapters are low-cost and have nearly identical counterparts within the 
IBM PC Network broadband family of adapters. The only essential differ- 
ence is that the baseband adapter transceivers drive twisted-pair media 
and the broadband adapter transceivers drive broadband media. In this 
sense. Adapter II(/A) and the Baseband Adapter(/A) are excellent exam- 
ples of “layered hardware” design. In fact, applications that use Broad- 
band II and II/A adapters must go to some length to determine whether 
they are actually running on Baseband Adapter and Baseband Adapter/A, 
respectively. 

An application must read the LAN adapter Transceiver Interface Regis- 
ter at the primary (alternate) port address 062Eh (062E). If the two high- 
order bits have a value of 00, then the adapter’s transceiver is a broadband 
transceiver. Otherwise, the two high-order bits have a value of 01 and the 
transceiver is a baseband transceiver. This inconsequential difference 
clearly illustrates that base adapters are absolutely identical, differing only 
in their transceivers, which are attached in the final assembly phases. 

Indeed, you could switch transceivers between Adapter II(/A) and 
Baseband Adapter(/A) and reinstall the adapters in the appropriate net- 
work without application impact other than changing the network 
adapter’s serial number. Thus, assumptions that given applications can 
run on IBM PC Network Broadband Adapter IIs (/As) but not on IBM PC 
Network Baseband Adapters (/As) are largely statements of support, not 
capability. In the final analysis, nothing prevents applications from going 
the extra mile to detect that they are executing on a PC Network base- 
band adapter and to terminate execution on that basis. Caveat emptor. 
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Ethernet Environment 

IBM markets Ethernet adapters manufactured by Ungermann-Bass of 
Santa Clara, California. The adapters are available from a business unit 
known as IBM Academic Computing Information Systems (ACIS), which 
works closely with academic institutions under joint development 
agreements involving a variety of technologies and communication envi- 
ronments. 


IBM LAN Programming Interfaces 

NetBIOS is one of five communication programming interfaces provided 
by IBM for its LANs. The various interfaces are 

• adapter card 

• Advanced Program-to-Program Communications (APPC) 

• Data Link Control (DLC) 

• direct 

• NetBIOS 

The relationships of these interfaces to NetBIOS are illustrated in Figure 
2-1. Detailed discussion of the other four major interfaces is beyond the 
scope of this book, but the following discussion summarizes their pur- 
poses. 


Adapter Card Interface 

The adapter card interface is the most difficult programming interface, re- 
quiring timing-sensitive logic, tricky interrupt processing, and nimble 
management of shared-RAM. For example, the IBM Token-Ring PC 
Adapter has a variety of independent interrupts that must be correctly 
handled in isolation or in mass. The adapter’s interrupt fecundity, com- 
bined with an error in the PC BIOS’s timer tick handler, eventually led IBM 
to introduce the CONFIG.SYS STACKS parameter (with DOS 3 -2) and the 
TIMERINT.SYS device driver (with the IBM LAN Support Program), re- 
spectively. In other words, this is an interface of last resort, though it is the 
interface used by LAN monitors to observe network traffic. 
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APPC Adapter 



Fig. 2-1. IBM PC LAN programming interface relationships. 


APPC Interface 

APPC is the interface provided for Systems Network Architecture (SNA) 
communication. It has numerous command sequences and control 
blocks associated with it, and is useful for peer-to-peer communications 
with IBM mainframes and other IBM processor applications that require 
SNA LU 6.2 communication capability. 

DLC Interface 

DLC provides the IEEE 802.2 EEC communication interface for IBM’s 
EAN adapters, which supports the IEEE type 2 EEC protocol guarantee- 
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ing notification of unsuccessful transmissions. DLC also provides the 
IEEE type 1 “connectionless” communications, sometimes referred to 
as “send and pray” communication, in which no guarantee of message 
delivery is provided and no notification is given in the event of transmis- 
sion problems. 

DLC offers the potential of higher performance communication than 
NetBIOS because it is “closer to the adapter.” As earlier indicated, Net- 
BIOS commands are converted into one or more DLC commands and 
then presented to the DLC interface. This is why NetBIOS data transmis- 
sion throughput rates often cannot exceed DLC data transmission 
throughput rates. 


Direct Interface 

The direct interface provides the ability to open, initialize, and close 
adapters, and permits programs to read and reset adapter logs, trace 
adapter activities, obtain status information, and operate adapter timers. 

IBM provides a wide spectrum of LAN adapters and programming in- 
terfaces, including NetBIOS. Clearly, a mechanism is needed to support 
these diverse adapters while simultaneously presenting a stable, uniform 
set of programming interfaces to applications. This is provided by the 
IBM LAN Support Program, which insulates applications from imple- 
mentation details of the specific LAN they operate on, allowing users to 
select the appropriate LAN for their requirements. 
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Application Services 


NetBIOS provides four categories of application services: 

• name support 

• datagram support 

• session support 

• general command 


NetBIOS Name Support 

An individual NetBIOS LAN adapter is distinguished from other adapters 
on its respective network by one or more network names, which allow 
LAN applications to direct their messages to specific adapters and indi- 
cate that their adapter originated the message. 

Each network name consists of l6 characters. Within a network 
name, each of the l6 characters is significant and uppercase is different 
than lowercase. The names you can create cannot have a value of binary 
zero or an asterisk (*) as the first character. IBM reserves the values of OOh 
to IFh for the l6th character and uses some of the reserved character val- 
ues with the IBM PC LAN Program. This is why you can only have a 15- 
character IBM PC LAN Program machine name. Finally, IBM reserves the 
use of “IBM” as the first three characters of any name. For a more com- 
plete discussion of NetBIOS naming considerations, refer to the NetBIOS 
Adapter Status Program discussion in Part II, of this book. 

The number of names an adapter can use (or is using) will vary, as can 
the number of adapters using a given name, but before an adapter can use 
any name, it must acquire the rights to register and use the name on the 
LAN. 
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NetBIOS initiates name registration activities in response to either of 
the two types of NetBIOS add-name commands; Add Name and Add 
Group Name. An adapter registers a network name by first broadcasting a 
network petition (a name-claim packet) to use the name. The type of 
packet, Name_Claim or Add_Group_Name_Claim, indicates whether 
the adapter wants to register the name as a unique name or as a group 
name respectively. 

Finally, once a name is successfully registered, any registered name 
except the first can be deregistered by issuing a NetBIOS Delete Name 
command. NetBIOS Adapter Reset commands erase the NetBIOS name 
table (except the first name), as does a system reset (Ctrl-Alt-Del) and 
powering off the workstation. 


Unique Names 

If an adapter tries to register a name as a unique name, then no other 
adapter operating on the LAN can have the same registered name or the 
registration attempt fails. If the name is currently registered, either as a 
unique name or as a group name, the offended adapter(s) issues a network 
complaint and the pending name registration command is refused. Other- 
wise, the adapter has the exclusive right to use the name on its LAN. 


Group Names 

If an adapter tries to register a name as a group name, then no other 
adapter can be using that name as a unique name or the registration at- 
tempt fails. If the name is in use as a unique name, the offended adapter 
issues a network complaint and the command to use the name is refused. 
Otherwise, the adapter has the nonexclusive right to use the name on the 
LAN. This allows other adapters to register the name as a group name, 
though not as a unique name. Group names are useful for sending mes- 
sages to collections of workstations such as departments or teams. 


The Name Table and Name Number 

If an attempted name registration fails, the failure is reported to the work- 
station application for subsequent analysis along with an appropriate er- 
ror return code. In the absence of network complaints, the adapter’s 
NetBIOS support places the name in a locally maintained, internal table 
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known as the NetBIOS name table. It then reports the name registration 
success to the LAN application along with a one-byte value. 

The one-byte value is an unsigned number referred to as the name’s 
NetBIOS name number. The name number is subsequently used in various 
NetBIOS commands associated with the name. NetBIOS assigns the value 
of the name number in an incremental, modulo 255, roundrobin manner. 
The values zero and 255 are never assigned, and the first entry is perma- 
nently assigned by the adapter based on its internal serial number. Thus, 
the numbers are assigned in the order 1, 2, 3, • • • 254,2,3,4, . . . 254, etc. 

Placing the name in the name table authorizes the adapter to subse- 
quently scrutinize registration petitions of other adapters wishing to reg- 
ister names. And, once added, a name can be deleted from the table, 
potentially allowing some other name to use it as a unique name. 

Note that the NetBIOS name table is a temporary table contained 
within RAM and is reconstructed after each system boot or adapter reset. 
Because each adapter has its own private name table, NetBIOS name res- 
olution is highly autonomous across the LAN, requiring no central name 
administration. If a NetBIOS module is supporting more than one LAN 
adapter within a workstation, each adapter also has its own independent 
NetBIOS name table. 

The Permanent Node Name 

All IBM LAN adapters have a unique six-byte number associated with 
them, guaranteed to be unique for every IBM LAN adapter and contained 
in an adapter ROM. The number is referred to by a variety of names; 

• permanent node name 

• permanent node address 

• burned-in address (BIA) 

• universally administered address 

• unit identification number 

• physical address 

• local node name 

For all IBM LAN adapters other than the PC Network LANA card, this 
address is in the range that is universally administered by the standards 
committees for LANs and has the two high-order bits set to zero. Under 
the native ROM NetBIOS, PC Network LANA adapter cards always have 
two bytes of binary zeros as the last two bytes of their permanent node 
name. The values of the two high-order bits in the remaining four bytes 
vary by adapter. 
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The permanent node name can be overridden at boot time with a six- 
byte locally administered address whose high-order bytes must have a 
value of X'4000'. This provides a new LAN hardware address for the 
adapter that replaces the permanent node name and is accomplished by 
specifying an appropriate value on the LAN adapter’s IBM PC LAN Sup- 
port Program device driver. DXMINFO.DOC has the appropriate details. 

If overridden, the locally administered address temporarily replaces 
the permanent node name as the adapter’s LAN hardware address until 
the system is rebooted. This provides the opportunity to omit or 
respecify the overriding locally administered address value or to replace 
the adapter with another that uses the same locally administered address. 

Note: NetBIOS applications cannot detect when a permanent node 
name has been overridden either on a local or remote adapter. NetBIOS 
always uses and returns the original permanent node name when an ap- 
plication obtains an adapter’s name. The only way to obtain both the per- 
manent node name and the current LAN hardware address is to issue a 
local DIR. STATUS request. This is not a NetBIOS request and is beyond 
the scope of this book. 

When any LAN adapter is initialized and active on a LAN, it has a 
unique six-byte number associated with it, the burned-in permanent node 
name. The number is also guaranteed to be unique on the LAN because it 
is registered in the NetBIOS name table as a unique name during adapter 
initialization (the six bytes are appended to 12 bytes of binary zeros to con- 
struct a unique l6-byte name). Because the registration happens during 
system initialization, the permanent node name is always the first entry in 
an adapter’s NetBIOS name table. Zero is an invalid NetBIOS name num- 
ber value, so permanent node name always has a name number value of 
one. 

The permanent node name serves as a LAN address that fingerprints 
all messages transmitted by an adapter, and serves as an identification 
anchorpoint for all messages transmitted to an adapter. Specifically, it is 
used to tell the adapter’s communication circuitry which messages 
should be ignored and which messages should be admitted into the 
workstation. This unique 48-bit value constitutes an adapter’s electronic 
message sieve. 


Symbolic Names 

Suppose you wrote a program to send a message to an associate named 
Melissa and you wished to send it to her workstation’s permanent node 
name, which you believe is X'4001020003404'. 
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This type of approach would be error prone because 
X'4001020003404' is an invalid address (it has one too many digits), and 
the program may need rewriting if Melissa’s workstation adapter is 
changed, perhaps for maintenance reasons. Thus, it would be conven- 
ient to personalize the LAN adapter address by using your associate’s nat- 
ural name, Melissa. Such pseudonyms are called symbolic names and are 
registered in the NetBIOS name table as either unique names or group 
names. 

Adapters can receive messages that are addressed to it using only 

• their 48-bit unique address derived from their unique serial num- 
ber 

• an indiscriminate general broadcast address of X'FFFFFFFFFFFF' 

• bit-mapped functional addresses 

• one value-mapped group address 

The last two of these methods are beyond the scope of this book. 

The name registration process is actually a LAN protocol for early 
name-usage conflict detection, and is an indiscriminate broadcast proto- 
col in preparation for subsequent communication requiring translation 
of symbolic names to 48-bit LAN addresses. 

Once a symbolic name has been resolved into an appropriate 48-bit 
address, NetBIOS needs only that address to conduct the communica- 
tion. The name used to make the association is nonessential until it is 
needed to resolve another, perhaps a different 48-bit address, to the sym- 
bolic name. Remember, symbolic names can be registered and deregis- 
tered. 


Datagram and Session Support 

Once an adapter becomes active in a network, application programs 
within the workstation can use NetBIOS to communicate with other ap- 
plications residing in the same or different workstations. The applica- 
tions can communicate using either datagrams or sessions. 


Datagram Support 

Datagrams are short messages whose size varies by NetBIOS implementa- 
tion and have no guarantee of delivery beyond a “best effort” by the 
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adapter. Regardless of whether the messages arrive safely, no receipt indi- 
cation is provided by NetBIOS. The intended recipient machine may 

• not exist 

• be powered off 

• not be expecting a datagram 

In these instances, and in the case of network problems, the 
datagram may never be received by any workstation. Datagram commu- 
nication is “send and pray” communication unless the receiving applica- 
tion takes explicit action to transmit a receipt acknowledgment. The 
primary advantage of datagram communication is that it can consume 
less workstation resource than session communication. 

There are two types of datagram communication; broadcast 
datagrams and plain datagrams. In both cases, the NetBIOS datagram 
transmission command references an existing local NetBIOS name num- 
ber, perhaps the permanent node name’s, that serves as the datagram ’s 
origin name. This name number may be associated with a local unique 
or group name. Finally, plain datagrams transmitted to group names and 
broadcast datagrams have a very low level of data security because they 
can be intercepted with very little effort. 

Broadcast Datagrams 

Broadcast datagrams are totally indiscriminate datagrams transmitted 
with a NetBIOS Send Broadcast Datagram command. Any adapter, in- 
cluding the transmitting adapter, can receive a broadcast datagram if it 
has previously issued a NetBIOS Receive Broadcast Datagram command. 

In general, broadcast datagram communication should be avoided 
because two applications within the same workstation could easily re- 
ceive broadcast datagrams intended for the other application. In addi- 
tion, applications that execute in workstations running the IBM PC LAN 
Program are specifically warned against using broadcast datagram com- 
munication. 

Plain Datagrams 

Plain datagrams are discriminate datagrams transmitted with a NetBIOS 
Send Datagram command. Unlike NetBIOS Send Broadcast Datagram 
commands, applications specify a recipient NetBIOS name with the 
Send Datagram command. Any adapter, including the transmitting 
adapter, can receive a datagram if it has previously added the appropriate 
recipient name and issued a Receive Datagram command to NetBIOS ref- 
erencing the number of the name specified in the command. 
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If an application specifies a name number of FFh in a receive 
datagram, the application can receive a datagram for any name in the Net- 
BIOS name table. This is referred to as a receive-any datagram. However, 
Receive Datagram commands for a specific name number have priority 
over Receive-Any Datagram commands. Figure 3-1 summarizes the rela- 
tionship between the two forms of Receive Datagram commands. 


Application Name/NcbNum LSN 



Receive Datagram for a specified name number 


Application Name/NcbNum LSN 



Receive-Any Datagram (lowest priority) 


Fig. 3-1. Receive Datagram command flavors. 
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Finally, plain datagrams can be transmitted to adapters using the 
name as a unique name, or to groups of adapters that share a group name. 


Session Support 

The second form of NetBIOS application communication is session 
communication. NetBIOS session support creates a reliable two-way 
data communication connection between two applications that can exist 
for extended periods. Such connections are sometimes referred to as vir- 
tual circuits. 

The communicating applications may reside within the same work- 
station (local sessions) or within different workstations (remote ses- 
sions). Each application constitutes one half ox side of the session. 

The primary advantage of session communication over datagram 
communication is that message-receipt status is presented to the trans- 
mitting application for every message it transmits. Datagram communi- 
cation provides message transmission status. However, session 
communication reliability comes with the slight overhead of creating 
and maintaining sessions and the packet acknowledgment protocol be- 
tween adapters. 

Creating Sessions 

Sessions are created when one application issues a NetBIOS Listen com- 
mand referencing a name in its NetBIOS name table. The application may 
use an existing name in the table such as the permanent node name or 
add one of its own. 

The Listen command also specifies the remote name that a petition- 
ing application must use to qualify as a session partner, and may use an 
asterisk (*) as the first character of the remote name. In this case, the re- 
maining 15 characters are ignored and the local NetBIOS allows the sec- 
ond application to use any name to qualify as a session partner. (Since 
session security depends on matching both names, one might correctly 
suspect such promiscuous behavior has its hazards.) 

A second application then issues a NetBIOS Call command, which 
references the name in its NetBIOS name table that the first application is 
expecting as a partner’s name. The Call command also references the 
name the first application referenced in its own NetBIOS name table. 
The double name match fulfills the criteria of both applications to create 
a session and the pending Listen and Call commands then complete. 
Note the sequence: first the Listen, then the Call. This sequence cannot 
be successfully reversed. 
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Each application then receives notification of session establishment 
and a one-byte unsigned value referred to as the NetBIOS Local Session 
Number (ESN) that the adapter associates with the session. The ESN is 
analogous to a PC-DOS file handle. 

NetBIOS assigns the ESN value in an incremental, modulo 255, round- 
robin manner. The values zero and 255 are never assigned. Thus, the num- 
bers are assigned in the order 1, 2, 3, . • . 254, 1, 2,3,4,... 254, etc. 

Even if both sides of the session are local sessions, note that two 
numbers are assigned — one for each side. In this case, either application 
can use either ESN. In general, there is no restriction that the two ESNs 
have the same value, even if they are both local sessions. The session cre- 
ation procedure is summarized in Eigure 3-2. 


Application 1 


Application 2 


Add name "Greg" (optional) Add name "Melissa" (optional) 

Listen for "Melissa" 
using the name "Greg" 

Call "Greg" using 
the name "Melissa" 



Session established, LSN == X Session established, LSN == Y 

Fig. 3-2. Session establishment. 

Receive Command Flavors 

After establishing a session, both sides can issue NetBIOS Send and Re- 
ceive commands to transfer data. If a given name is used to create several 
sessions, an application can also issue a NetBIOS Receive-Any-for-a-Spec- 
ified-Name (Receive-Any) command, which provides received data from 
any session associated with a specified name. More generally, the applica- 
tion can issue a NetBIOS Receive- Any-for-Any-Name (Receive-Any-Any) 
command, which provides received data from any existing session the 
adapter has actively established. 

In the event a message arrives that could satisfy more than one of 
these types of NetBIOS Receives, the following hierarchy is observed: 

1 . Receive (highest priority) 

2 . Receive-Any-for-a-Specified-Name 

3 . Receive- Any-for-Any-Name (lowest priority) 

The behavior of the various Receive flavors is summarized in Eigure 3-3- 
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Send Command Flavors 

Applications issue NetBIOS Send commands to transfer data to the other 
application. The Send command allows the application to send messages 
ranging in size from zero bytes to 64K minus 1 bytes of data; the data 
must be in contiguous memory. The application can also issue a NetBIOS 
Chain Send command that allows data to reside in buffers located in two 
different storage areas. 


Application Name/NcbNum LSN 



Application Name/NcbNum LSN 



Greg/03h 

1 




□ OShCZ 


Receive-Any 





NcbNum -03h 


I133h[ll 









pAChcJ 






Melissa/F2h 

2Dh 


4Ch 



Receive-Any-for-a-Specified-Name 


Fig. 3-3. Receive command flavors. 
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With a Chain Send command, data within each of the buffers must be 
in contiguous memory, though the two buffers themselves do not have 
to be contiguous. Moreover, each data block can range from zero bytes to 
64 k minus one bytes, allowing up to 12 8K minus two bytes to transfer 
with one Chain Send command. 


Send and Receive Considerations 

First note that a NetBIOS Chain Send command exists, but a NetBIOS 
“Chain Receive” command does not. NetBIOS allows applications to re- 
ceive part of a transmission and issue subsequent NetBIOS Receives to 
receive the remainder of the message. This is true for messages that origi- 
nate from both Send and Chain Send commands. Conversely, a single 
NetBIOS Receive command can usually receive messages transmitted 
with a Chain Send command provided the message is not too large. In 
any event, the receiving application cannot detect whether a message 
was transmitted with a Send versus a Chain Send unless the size of the 
total message exceeds 64K minus one bytes. This is because Chain Send 
command data originating in two separate buffers always arrives seam- 
lessly with no indication of the original buffer boundaries. 

The only stipulation for an application that partially receives a mes- 
sage is that it not delay “too long” to receive the entire message. Specific- 
ally, when the session is established, each side specifies Receive and Send 
time-out threshold periods. If the Send threshold period is exceeded be- 


Application Name/NcbNum LSN 



Greg/03h 





bo5hE 








bashs 






Receive-Any 


pAChCl 

■' j 

NcbNum = FFh 





Melissa/F2h 





I]2DhEI 








ll]4ChC: 




r1 



Recelve-Any-for-Any-Name (lowest priority) 


Fig. 3-3. (Cont.) 
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fore the message is completely received, the Send times-out and the entire 
session is terminated by the sending adapter. In this instance, both sides of 
the session are notified of the consequences of the receiver’s lethargy. 

Send No-Ack and Chain Send No-Ack Considerations 

The Send No-Ack and Chain Send No-Ack commands first appeared with 
version 1.02 of the IBM LAN Support Program. They differ from the Send 
and Chain Send commands, respectively, by eliminating unnecessary 
NetBIOS-to-NetBIOS data-receipt acknowledgments occurring with 
prior IBM NetBIOS implementations. 

Caution: The Send No-Ack and Chain Send No-Ack commands are 
not in the original NetBIOS definition and may not be universally recog- 
nized by other NetBIOS implementations, including prior IBM NetBIOS 
implementations and the IBM PC Network Protocol Driver Program. Us- 
ing them may produce nonportable results because they require new 
command codes and generate new return code values for themselves 
and the Send, Chain Send, Receive, and Receive-Any commands. 

Ending Sessions Gracefully 

Sessions are ended by one or both sides issuing a NetBIOS Hang Up com- 
mand that specifies the LSN of the session to be terminated. The other 
application is notified of the session termination when it issues a subse- 
quent session command. An application can issue a NetBIOS Session Sta- 
tus command that will indicate the status of a session — existing or 
cancelled. 


General Commands 

The NetBIOS general commands provide such NetBIOS services as 

• Reset 

• Adapter Status 

• Cancel and Unlink 

• Find Name 

• Trace 


Reset Command 

The Reset command forces the adapter to an initialized state. This termi- 
nates all sessions and removes all names from the NetBIOS name table ex- 
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cept for the permanent node name. The Reset command optionally 
specifies the maximum allowable number of NetBIOS commands that can 
be pending at one time as well as the maximum number of sessions that 
concurrently exist within the adapter. Minimizing these values can increase 
performance by freeing up valuable work space for more network buffers. 


Adapter Status Command 

The Adapter Status command allows you to query a NetBIOS adapter and 
retrieve operational information such as detected LAN error counts and 
the adapter’s NetBIOS name table. The queried adapter could be a local 
adapter or a remote adapter on the LAN. In some environments, using 
the Adapter Status command to query a remote adapter is an excellent 
way to determine whether the adapter and a workstation is hung or just 
the workstation is hung. (Adapters can sometimes operate from LAN in- 
terrupts though the workstation is hung.) 


Cancel and Unlink Commands 

The NetBIOS Cancel command allows applications to cancel commands 
that have not completed. The NetBIOS Unlink command allows a PC 
Network LANA adapter that has booted using RPL to disconnect from the 
RPL server machine. The Unlink command is intercepted by the PC Net- 
work LANA NetBIOS and converted to a Hang Up command that uses 
information stored in high RAM. 

The Unlink request is only valid for the primary adapter and always 
returns a zero (successful) return code. For all other IBM LAN adapter 
NetBIOS implementations, the Unlink command is provided as a com- 
patibility feature for the PC Network LANA card and performs no func- 
tion. See Part III for a complete discussion of the RPL process. 


Find Name Command 

The NetBIOS Find Name command locates adapters that are using a sym- 
bolic name specified in the Find Name command. This is similar to an 
Adapter Status command except NetBIOS returns one adapter response 
at most to an Adapter Status command. (Several adapters sharing a group 
name may respond, but only one response is returned to a requesting 
application.) 
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In the case of the Find Name command, several adapters can also re- 
ply if they share a group name, but theoretically speaking, all the re- 
sponses are eligible to be returned to the requesting application. An 
Adapter Status command returns all names within the target adapter’s 
NetBIOS name table and the NetBIOS Find Command returns the 
adapter routing information for the adapters that are using the name. 

The adapter routing information is only relevant in interconnected 
LANs such as the IBM Token-Ring because the information indicates the 
route(s) a message can take to arrive at a specific workstation. This rout- 
ing information identifies the bridges connecting separate physical rings. 
Messages must traverse these bridges to reach the LAN the recipient 
workstation is on. 

Trace Command 

The Trace Command activates a trace of all commands issued to the Net- 
BIOS interface. Its primary objective is to provide support for diagnostic 
programs. In the event your implementation does not have a Trace com- 
mand, you can write one yourself by intercepting all INT 5C requests. 
You should only analyze interrupt requests where the ES:BX register pair 
point to a byte in memory that has a value greater than 02 h. When ES;BX 
point to values of OOh, Olh, and 02h, the request is a DLC IEEE 802.2 LLC 
request. This topic and the general Trace command is beyond the scope 
of this book. 


Issuing NetBIOS Commands 

Applications issue NetBIOS commands by first zeroing out a 64-byte area 
of memory. This prevents residual data from causing NetBIOS to wildly 
branch into random memory when the command completes. The appli- 
cation then uses the area to construct a NetBIOS Control Block or Neb. 
Completing the control block consists of filling various fields that are re- 
quired by the particular command that will be issued. Failure to com- 
plete the Neb fields correctly can hang the user’s machine because 
uncompleted fields are initialized to all zeros. For example, in the case of 
PC-DOS, if the Neb specifies a Receive command and the receive data 
buffer address is inadvertently not specified, the arriving data will oblig- 
ingly be placed at address 0000:0000 overlaying and corrupting your 
machine’s interrupt vectors. That can be a difficult error to isolate 
though its effect is more than somewhat obvious. 
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After filling in the Neb, the application then points the ES:BX register 
pair at the Neb and issues an INT 5C interrupt request. When NetBIOS 
can report status on the request, it does. However, the particular way it 
does this varies with the way the particular request was issued. 


C Example 

Listing 3-1 shows how to issue a NetBIOS interrupt request using the C 
language. This particular figure issues a NetBIOS interrupt directly to the 
native NetBIOS interrupt. For IBM PCs, an alternate method uses a PC- 
DOS INT 2 Ah request specifying a value of 0400h or 0401h in the AX 
register. In both cases, the ES;BX register pair point to a valid Neb. 

Listing 3-1. C Fragment Illustrating a Direct NetBIOS 
Interrupt Request 

#define USGC unsigned char 
^define USGI unsigned 
#define USGL unsigned Long 

/^define NetbiosInt21 FunctionCode ((USGC) 0x2A) 

#define NetbiosIntSC ((USGC) 0x50 

voi d Netbi osRequest (NebPoi nter) 
struct Neb *NcbPointer; 

{ 

struct SREGS SegRegs; 

union REGS InRegs, OutRegs; /* defined in dos.h */ 
struct Neb far *NcbPtr = (struct Neb far *) NebPointer; 

segread(&SegRegs) ; 

SegRegs.es = FP_SEG(NcbPtr) ; 

InRegs.x.bx = FP_0FF (NcbPtr) ; 

int86x(NetbiosInt5C, SlnRegs, &0utRegs, &SegRegs); 

> 


An AX value of 0401 h indicates PC-DOS should not automatically re- 
try the command if the command failed. An AX value of 0400h indicates 
PC-DOS should retry the command if the command failed because 

• the adapter does not have the resources necessary to complete the 
command successfully 

• the adapter is busy and cannot handle the request 
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• the other workstation rejected our application’s attempt to start a 
communication session with it 

The INT 2 A approach is sometimes necessary for total coexistence 
with the IBM PC LAN Program. However, before first using this interface, 
an application must test the version of PC-DOS to verify it is version 31 
or later, and then determine whether the IBM PC LAN Program is in- 
stalled (see Chapter 6). 


MASM Example 

Listing 3-2 illustrates how to issue a NetBIOS interrupt request using 
MASM. Again, this particular figure issues a NetBIOS interrupt directly to 
the native NetBIOS interrupt in lieu of a PC-DOS INT 2Ah request with 
AH set to 0400h or 0401 h. 


Listing 3-2. 

MASM Fragment Illustrating a Direct NetBIOS 
Interrupt Request 

Netbiosint equ 5Ch 

; NETBIOS interrupt vector 

mov 

BX, offset Neb 

mov 

AX,CS 

mov 

ES,AX ; ES:BX ==> Neb 

int 

Netbiosint 


Testing for the Presence of NetBIOS 

Before an application can safely issue a NetBIOS request, it must deter- 
mine if NetBIOS is present. For IBM PCs, this process varies with the 
model. 


The Original IBM PC and PC-XT Test 

The original IBM PC and PC-XT BIOS POST procedures initialize inter- 
rupt vectors that BIOS does not need to OFFSET: SEGMENT values of 
0000:0000. Issuing a NetBIOS request in one of these machines to an 
uninitialized interrupt is virtually guaranteed to hang the machine. 
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The Test for Other IBM PCs 


The IBM PC-AT and follow-on machine BIOS POST procedures point 
the interrupt vectors that BIOS does not need at an immediate IRET in- 
struction. The SEGMENT value of the IRET instruction is always FOOOh. 
Thus, issuing a NetBIOS request to an uninitialized interrupt in one of 
these machines is harmless though unproductive. Chapter 4 contains a 
program that tests correctly for NetBIOS presence. 

To summarize, there are four categories of NetBIOS commands, each 
with several members: 


Name Support 


Datagram Support 


Session Support 


General Commands 


Add Name 

Add Group Name 

Delete Name 

Receive Datagram 

Receive Broadcast Datagram 

Send Datagram 

Send Broadcast Datagram 

Call 

Listen 

Send 

Send No-Ack 
Chain Send 
Chain Send No-Ack 
Receive 
Receive-Any 
Hang Up 
Session Status 
Reset 
Cancel 

Adapter Status 
Unlink 




Chapter 4 


Ncb/Mcb Fields 


IBM Token-Ring literature refers to the Neb as the Message Control block 
or Mcb, but we will use the term Neb exclusively. 

The Neb is 64 bytes, with 13 fields and one l4-byte reserved area. 
Table 4-1 diagrams the Neb and its fields. The C language Neb structure is 
illustrated in Listing 4-1 and the MASM structure is illustrated in Listing 4- 
2. The chart on the inside front cover illustrates when a field is an input 
field and when it is an output field. The fields are discussed in greater 
detail in Part IV. 


Table 4-1. The Neb Fields 


Offset 

Field Name 

Length 
in Bytes 

Field Structure 

+ 00 

Command 

1 

□ 

+ 01 

Return Code 

1 

□ 

-1-02 

Local Session Number 

1 

□ 

+ 03 

Name Number 

1 

□ 

-1-04 

Buffer Address 

4 

□□□□ 

-1-08 

Buffer Length 

2 

□□ 

4-10 

Call Name 

l6 

□□□□□□□□□□□□a □□□ 

+ 26 

Name (Local) 

16 

□□□□□□□□□□□□□□□□ 

+ 42 

Receive Time Out 

1 

□ 

+43 

Send Time Out 

1 

□ 


57 
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Table 4-1. (cont.) 



Length 


Offset 

Field Name 

in Bytes 

Field Structure 

+44 

Post Routine Address 

4 

□□□□ 

+48 

LANA Number 

1 

□ 

+49 

Command Complete Flag 

1 

□ 

+ 50 

Reserved Field 

14 

□□□□□□□□□□□□□□ 


Listing 4-1. A C Neb Structure 

^define USGC unsigned char 
#define USGI unsigned 
^define USGL unsigned Long 

struct Neb 


USGC 

NebCommand; 

/* 

command code 

*/ 


USGC 

NebRetCode; 

/* 

return code 

*/ 


USGC 

NcbLsn; 

/* 

local session number 

*/ 


USGC 

NebNum; 

f* 

Datagram ADD NAME table entry 

*/ 


char 

* NebBufferOffset; 

/* 

I/O buffer offset 

*/ 


USGI 

NebBufferSegment; 

/* 

I/O buffer segment 

*/ 


USGI 

NcbLength; 

/* 

length of data in I/O buffer 

*/ 


char 

NebCal lNameC16] ; 

/* 

remote system name for CALL 

*/ 


char 

NcbName[16] ; 

/* 

local adapter network name 

*/ 


USGC 

NebRto; 

/★ 

receive timeouts in 1/2 second 

uni ts 

*/ 

USGC 

NebSto; 

/* 

send timeouts in 1/2 second 

units 

*/ 

char 

* NebPostRtnOffset; 

/* 

offset of post routine 

*/ 


USGI 

NcbPostRtnSegment; 

/* 

segment of post routine 

*/ 



USGC NebLanaNum; /* network adapter number to execute cmd */ 

USGC NcbCmdCplt; /* OxFF ==> command pending, else empLted */ 

char NebReservedAreaCH]; /* work area for network card */ 

> ZeroNcb; /* prototype NCB for sizeof calcs */ 
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Listing 4-2. A MASM Neb Structure 
Neb Structure 


Neb struc 


Ncb_Command 

db 

OOh 

;Ncb 

Ncb_RetCode 

db 

OOh 

;Ncb 

Ncb_Lsn 

db 

OOh 

;Ncb 

Ncb_Num 

db 

OOh 

;Ncb 

Ncb_BufferOf f 

dw 

OOOOh 

;Ncb 

Ncb_BufferSeg 

dw 

OOOOh 

;Ncb 

Ncb_Length 

dw 

OOOOh 

;Ncb 

Ncb_Cal IName 

db 

16 dup(O) 

;Ncb 

Ncb^Name 

db 

16 dup<0) 

;Ncb 

Ncb_Rto 

db 

OOh 

;Ncb 

Ncb_Sto 

db 

OOh 

;Ncb 

Neb^PostOff 

dw 

OOOOh 

;Ncb 

Ncb_PostSeg 

dw 

OOOOh 

;Ncb 

Neb^Lana^Num 

db 

OOh 

;Ncb 

Ncb_Cmd_Cplt 

db 

OOh 

;Ncb 

Ncb_Reserve 

db 

U dup(O) 

;Ncb 

Neb ends 




command field 

return code 

local session number 

name number from AddName 

message buffer offset 

message buffer segment 

message buffer length (in bytes) 

remote name 

AddName 

receive timeout 
send timeout 
post routine offset 
post routine segment 
adapter number 

OFFh ==> command pending indicator 
reserved area 


Command 


The Neb command field is a one-byte field containing the NetBIOS com- 
mand code for the desired operation. If the high-order bit of the com- 
mand code is zero, NetBIOS accepts the request and returns to the 
application when the command is completed. This is referred to as the 
wait option. Clearly, only one wait-option command can be pending at a 
time. 

Although some commands such as Reset, Cancel, and Unlink are 
guaranteed to complete, other commands only complete under certain 
conditions. If such a command never completes, NetBIOS never returns 
and the machine hangs in an infinite NetBIOS command completion 
spin-loop. To avoid this, applications can set the high-order bit of the 
command field to a binary one value for all commands except the Reset, 
Cancel, and Unlink commands. This is referred to as the no-wait option. 
In this situation, NetBIOS returns immediately with an initial return code 
(in AL for the IBM PC) and expects that the Neb and all associated data 
areas will remain undisturbed until the command can complete. 
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If NetBIOS accepts the command, it queues it for subsequent action 
which allows several requests to be pending at one time. It also places an 
FFh in the Neb command complete field, indicating the command has 
been queued but has not completed. When the command completes, 
NetBIOS posts the final return code in both the Neb return code field 
and the Neb command complete field. It also inspects the Neb post 
routine address field to see if it is all zeros. If it is not, NetBIOS immedi- 
ately enters the code in a disabled state as if the code were an interrupt 
routine. 

The code must subsequently return to NetBIOS with an IRET in- 
struction and should enable interrupts if ifg activities require any signifi- 
cant time to accomplish. Moreover, a post routine should not issue PC- 
DOS requests because they may have been interrupted to invoke the post 
routine and PC-DOS is not reentrant. However, a post routine can issue 
other NetBIOS requests. 

Finally, some programs occasionally terminate execution and return 
to the operating system with NetBIOS commands still pending. This is 
equivalent to leaving without disabling enabled hardware interrupts. 
NetBIOS will destroy memory in the 64-byte Neb area if the Neb eventu- 
ally completes. At the very worst, NetBIOS will see that the NetBIOS 
post routine address is not zero when the command completes, perhaps 
because your word processor has overlaid the area where the Neb re- 
sided. Thus, NetBIOS might wildly branch into memory based on the 
unpredictable post routine address value, causing your machine to peri- 
odically hang for inexplicable reasons, such as divide-by-zero interrupts 
during periods of apparent workstation inactivity. 

Be warned. Pending NetBIOS requests must be canceled before an 
application completes and returns to the operating system. This is done 
by explicitly canceling all pending Nebs or possibly by issuing an adapter 
Reset command. Failing to do this can result in debugging sessions that 
are memorably excruciating. 


Return Code 

The Neb return code field is a one-byte field that eventually contains the 
value of the command’s final return code. If it is zero after command 
completion, the command completed successfully. Otherwise, a prob- 
lem was detected, though it may not be of any consequence. Appendix C 
lists the NetBIOS Neb return codes. 
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Local Session Number 

The Neb local session number field is a one-byte field containing the lo- 
cal session number associated with a command. NetBIOS assigns the 
value of the local session number in an incremental, modulo 255, round- 
robin manner. The values zero and 255 are never assigned. 


Name Number 

The Neb name number field is a one-byte field containing the NetBIOS 
name table name number associated with a command. NetBIOS assigns 
the value of the name number in an incremental, modulo 255, round- 
robin manner. The values zero and 255 are never assigned. The first en- 
try’s number, name number one, is always the permanent node name’s 
number. 


Buffer Address 

The Neb buffer address field is a four-byte field containing a memory 
pointer to a data buffer. In the case of the IBM PC, the data is in the OFF- 
SETSEGMENT format. 


Buffer Length 

The Neb buffer length field is a two-byte field indicating the size of the 
buffer pointed at by the Neb buffer address field. 


Call (Remote) Name 

The Neb call name field is a l6-byte field typically, but not always, con- 
taining a remote name associated with the request. All 16 bytes are signifi- 
cant and are used. In some instances, such as local session creation, the 
name may he a local name instead of a remote name. 
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In the case of a Chain Send Command, the Neb call name field does 
not contain a name. The first two bytes are used to indicate the length of 
the Chain Send’s second buffer. The next two bytes contain the second 
buffer’s offset, and the last two bytes contain the buffer’s segment ad- 
dress. While using the Neb call name field in this manner may seem a bit 
odd, it has the advantage of minimizing the Neb size while satisfying field 
alignment requirements for many C compilers. 


(Local) Name 

The Neb (local) name field is a l6-byte field containing a local name asso- 
ciated with the request. All 16 bytes are significant and are used. The first 
character cannot have a value of binary zero or be an asterisk (*). In addi- 
tion, IBM reserves the values of OOh to IFh for the l6th character and the 
values “IBM” as the first three characters of any name. 


Receive Time Out 

The Neb receive time out field is a one-byte field used with Call and Lis- 
ten commands. It specifies the number of half-second periods that a Re- 
ceive (Receive, Receive -Any) command can wait for completion before 
timing-out and returning an error. The time-out threshold is established 
at session creation and cannot be subsequently altered. Specifying a 
value of OOh indicates that there is no time-out threshold for Receive 
commands associated with the session. 


Send Time Out 

The Neb send time out field is a one-byte field used with Call and Listen 
commands. It specifies the number of half-second periods that a Send 
command (Send, Send No-Ack, Chain Send, Chain Send No-Ack) can 
wait for completion before timing-out and returning an error. The time- 
out threshold is established at session creation and cannot be subse- 
quently altered. If a Send command times-out, the session is terminated. 
Specifying a value of OOh indicates that there is no time-out threshold for 
Send commands associated with the session. 
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Post Routine Address 


The Neb post routine address field is a four-byte field containing a mem- 
ory pointer to a routine that is executed when the command completes. 
NetBIOS only inspects this field when the command has specified the 
no-wait option; otherwise, it is ignored. In the case of the IBM PC, the 
data is in the OFFSETSEGMENT format. See the related Neb command 
field for more information. 


LANA Number 


The Neb LANA number field is a one-byte field indicating which adapter 
should handle the command. In the case of the IBM PC LAN adapters, 
there are at most two adapters. The primary adapter is LANA adapter 
zero; the alternate adapter is LANA adapter number one. 


Command Complete Flag 


The Neb LANA number field is a one-byte field that indicates whether a 
command that specified the no-wait option has completed. If the value 
in this field is FFh, the command has not completed. Otherwise, the field 
contains the final command return code. See the Neb command field for 
more information. 


Reserved 


The Neb reserved field is a 14-byte reserved area that NetBIOS may use to 
return extended error information. In addition, NetBIOS uses it as an in- 
termittent scratchpad during request processing. Application programs 
should never use the Neb reserved field because if it is tampered with, 
NetBIOS’s behavior may be unpredictable. 
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Sample C Progmm to Tfest for NetBIOS Presence 

We now look at our first C NetBIOS program. Listing 4-3, PRESENCE. C, 
is a sample C program that should correctly test for the presence of Net- 
BIOS on all IBM PC models. In the event that this program does not work 
correctly with your machine or future IBM machines, you should use a 
debugger to inspect the INT 5C interrupt vector at segment OOOOh, offset 
0170h, and correct to program accordingly. 

Listing 4-3. PRESENCE.C 

(l/define LINT_ARGS 

#incLude <dos.h> 

^include <stdio.h> 

#incLude "netbios2.h” 

struct SREGS SegRegs; 

#if defined(LINT_ARGS) 

extern int mainCint argc,char * *argv); 

extern int CheckDosIVs(void) ; 

extern void IssuelnvalidNetbiosRequest (void) ; 

extern void ClearNcbCstruct Neb *NcbPtr); 

extern void NetbiosRequest (struct Neb *NcbPointer) ; 

extern void Logo(void); 

#endi f 

int main(argc, argv) 
int arge; 
char *argv[3; 

{ 

unsigned char temp; 

LogoO; 

if (CheckDosIVsO ) 

I ssueinva I i dNetbi osRequest ( ) ; 

printf ("\n\nProgram ending. . .\n"); 

return 0; 

> 

#define D0S_INT_21 0x21 
^define DOS FETCH IV 0x35 
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Listing 4-3. (cont.) 


int CheckDosIVsO 

union REGS InRegs, OutRegs; 
struct SREGS SegRegs; 

InRegs. h. ah = DOS_FETCH_IV; 

InRegs. h.al = NetbiosIntSC; 

int86x(DOS_INT_.21 , &InRegs, SOutRegs, SSegRegs); 

printf ("\n\nNetBIOS Int 5Ch IV SEGMENT:OFFSET == %04X:%04X. . 

SegRegs.es, OutRegs. x.bx); 


switch (SegRegs.es) -C 

case 0x0000 : printf (”\n\nNetBIOS IV segment == 0x0000\x07") ; 
return FAILURE; 
break; 

case OxFOOO : printf ("\n\nNetBIOS IV segment == 0xF000\x07") ; 
return FAILURE; 
break; 

default : printf ("\n\nNetBIOS IV segment appears valid..."); 

return SUCCESS; 
break; 

> 

> 

^define ERROR_INVALID_COMMAND 0x03 
void IssueInvalidNetbiosRequest () 

struct Neb PresenceNcb; 

ClearNcb(&PresenceNcb) ; 

PresenceNcb. NebCommand = NETBIOS_INVALID_COMMAND; 

NetbiosRequest (&PresenceNcb) ; 

if (PresenceNcb. NebRetCode == ERROR_INVALID_COMMAND) 

printfC'and NetBIOS is present..."); 

else 

printf ("but NetBIOS is not present ... \x07") ; 
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Listing 4-3. (cont.) 


> 

void CLearNcb(NcbPtr) 
struct Neb *NcbPtr; 

i nt i ; 

char *CharPtr; 

CharPtr = (char *) NcbPtr; 

for ( i = 0; i < sizeof (ZeroNcb) ; i++ ) 

*CharPtr++ = 0x00; 

> 

. void NetbiosRequest (NebPointer) 
struct Neb *NcbPointer; 

union REGS InRegs, OutRegs; /* defined in dos.h */ 
struct Neb far *NcbPtr = (struct Neb far *) NebPointer; 

segread(&SegRegs) ; 

SegRegs.es = FP_SEG(NcbPtr) ; 

InRegs. x.bx = FP_OFF(NcbPtr) ; 

int86x(NetbiosInt5C, SlnRegs, &0utRegs, SSegRegs); 

> 

void LogoO 

printf C'Xn*- NetBIOS Presence Test Program"); 
printfC’ © Copyright 1988 W. David Schwaderer 

> 

Note that the program also issues an invalid NetBIOS request to en- 
sure that the NetBIOS interrupt vector is actually being used by NetBIOS 
and has not been captured by some other program. However, if the inter- 
rupt vector has been captured by another program that reflects the 
request to an uninitialized NetBIOS interrupt, the results may be cata- 
strophic. The NetBIOS presence testing process is significantly compli- 
cated by the existence of the NETBIOS.COM module. NETBIOS.COM 
can be loaded anywhere and is generally indistinguishable from a debug- 
ging program that may pass the interrupt (reflect) to an uninitialized in- 
terrupt vector. 
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The IBM PC-DOS LAN 
Support Program 


As indicated in Figure 2-1, the IBM LAN Support Program provides sup- 
port for the NetBIOS, DLC, and direct interfaces in PC-DOS environ- 
ments. It replaces the predecessor NETBEUI.COM and TOKREUI.COM 
programs and provides communication interface support for all of IBM’s 
LAN adapters. 

The IBM LAN Support Program can simultaneously support up to 
two adapters within the same machine and they do not have to be of the 
same type. One adapter is referred to as the primary and has a program- 
ming address of zero, and the other, if present, is referred to as the alter- 
nate adapter and has a programming address of one. 

Since a given adapter requires specific support programming, the IBM 
LAN Support Program provides families of device drivers that enable users 
to configure the specific support they require. As an example, this allows 
the original IBM PC Network LANA card to use standard LLC protocols. 

Conversely, using another program named the IBM PC Network 
Protocol Driver allows IBM PC Network Adapter II and II/A cards to com- 
municate with IBM PC Network LANA cards using the original SMP 
protocols. In any event, the protocol used is invisible to NetBIOS appli- 
cations unless an application that uses one protocol tries to communi- 
cate with an application using another. That would never work in any 
circumstance. Hence, the operative concept throughout IBM LAN sys- 
tem offerings is communication flexibility within protocols. 


What Is Its Role? 

The IBM LAN Support Program provides users of IBM LAN adapters a 
significant degree of independence from the specific programming and 
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Operating characteristics of the particular LAN they are using. This en- 
ables users to select the appropriate type of media and LAN topology for 
their environments, independent of their particular application require- 
ments. However, this independence is not universally granted without 
restrictions. 

It is rather remarkable to folks familiar with the original PC Network 
LANA card’s design that it can communicate using the 802.2 LLC proto- 
cols. Among other things, this capability enables PCs using the original 
PC Network LANA card to communicate with Token-Ring devices via an 
intermediary PC running the IBM Token-Ring/PC Network Interconnect 
Program. However, the PC Network adapter card used in the gateway 
cannot be an original PC Network LANA card. It has to be a PC Network 
Broadband Adapter II or II/A because there must be no other communi- 
cation adapter in a PC if an original PC Network LANA card using LLC 
protocols is present. 

The IBM LAN Support Program provides the “glue” for the various 
IBM LAN adapters, and that is a very significant role though it sometimes 
involves a few restrictions. 


NetBIOS Parameter Summary 

The IBM LAN Support Program NetBIOS device driver, DXMTOMOD. 
SYS, is one of eight device drivers included on the Program diskette. 
DXMTOMOD, SYS has 26 parameters that can optionally appear on the 
CONFIG.SYS device driver specification line. One of the parameters, 
STATIONS, helps determine the number of transmit buffers as well as the 
size of both the transmit and receive buffers. This parameter can signifi- 
cantly affect NetBIOS performance. Other parameters such as DLC. 
MAXIN, DLC.MAXOUT, DLC.Tl, and DLC.T2 parameters affect Net- 
BIOS performance as well. 

The rest of the parameters either affect memory consumption or per- 
formance during error recovery (see Table 5-1). Consult DXMINFO.DOC 
for details concerning the other device drivers and how to specify the 
parameter values for primary and alternate adapters. 


DLC, LLC, SAPs, and Link Stations Preliminaries 

A Service Access Point (SAP) is a constructed code point that identifies 
applications to the DLC and LLC software (see Table 5-1). All 802.2 
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Table 5-1. Effect of the DXMTOMOD.SYS STATIONS Parameter 


Link Station Count Transmit Buffer Count Transmit Buffer Size Receive Buffer Size 


Token-Ring I Adapter (8K-byte shared-RAM) 


01-06 

2 

1048 

280 

07-12 

1 

1048 

192 

13-18 

1 

600 

144 

19-24 

1 

600 

112 

> 24 

1 

600 

96 


Token-Ring II Adapter and Token-Ring/A Adapter (l6K-byte shared-RAM) 


01-32 

2 

2040 

280 

33-48 

2 

1048 

280 

49-64 

1 

1048 

280 

> 64 

1 

600 

144 



PC Network Adapter 


01-32 

2 

2040 

280 

33-48 

2 

1048 

280 

49-64 

1 

1048 

280 

> 64 

1 

600 

144 


Source: DXMINFO.DOC version 1,02 


frames (transmitted packets) contain a one-byte SAP value. DLC and LLC 
logic use this value to determine the destination application and where 
to obtain resources (e.g., storage) to handle a frame. The NetBIOS SAP 
value is OFh and the SNA value is 04h; there are others. DLC and LLC 
software both permit multiple simultaneous active SAPs. 

SAPs own link stations and can own more than one link station simul- 
taneously. Link stations are components which DLC and LLC use to iden- 
tify communicating adapters. When NetBIOS establishes a session, a 
local link station connects with a remote link station, establishing a path. 
The session uses this path for all frames associated with the session. LLC 
insures the integrity of the data and handles the acknowledgment and 
sequencing of the frames. When a session abnormally ends, there is a 
connection problem between two link stations. 

For each of the parameters we are going to discuss, the expression in 
parentheses indicates the parameter’s abbreviation as well as its allowa- 
ble range or values. Where appropriate, the value following the ‘‘default 
= ” is the default value. Parameters that begin with DLC are given to LLC 
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software to specify characteristics of NetBIOS link stations. Note that 
this information is extracted from the DXMINFO.DOC version 1.02 and 
is subject to change. For more current information, consult the 
DXMINFO.DOC file on your current IBM PC LAN Program Diskette. 


ADAP.ADDR.NOT.REYERSED 

The ADAP.ADDR.NOT.REVERSED (ANR=Y/N, default = N) parameter 
specifies the order in which an Adapter Status command should present 
the bytes composing an adapter’s permanent node name. 

PC Network LANA Adapter Cards 

Using native ROM NetBIOS, PC Network LANA adapter cards always 
have two bytes of binary zeros as the last two bytes of their permanent 
node name. If a PC Network LANA adapter has a permanent node name 
of X'112233440000', specifying ANR=Y causes an Adapter Status to 
present the value as X'000011223344'. Otherwise, the value is presented 
as X'443322110000'. This means, with either selection of the ANR value, 
the PC LAN Program version 1.02 does not provide the value a native 
LANA NetBIOS provides. (Refer to Figure 5-1.) 


Non-LANA Permanent Node Name — ► X'11 2233445566' 


ANR = Y — X'11 2233445566' 
ANR = N — ► X'665544332211' 


LANA Permanent Node Name — ► X'11 2233440000' 


ANR = Y — ► X'00001 1223344' 

ANR = N X'4433221 10000’ 

Fig. 5-1. Effect of ANR parameter, LAN Support Program version 1.02. 


Other Network Adapter Cards 

If the ADAP.ADDR.NOT.REVERSED parameter is specified as Y, an 
Adapter Status command presents the adapter’s permanent node name 
the way it exists on the adapter. If omitted or specified as N, an Adapter 
Status command presents the adapter’s permanent node name in a byte- 
reversed format. (Refer to Figure 5-1.) 
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CLOSE.ON.RESET 

The CLOSE.ON.RESET (CR=Y/N, default = N) parameter specifies 
whether NetBIOS should close and reopen the adapter whenever a Net- 
BIOS Reset command is issued. An adapter close and reopen can take a 
few seconds to complete. 

If omitted or specified as N, the close and reopen is not performed 
when the adapter is Reset. In this case, the Reset command takes signifi- 
cantly less time to complete because it only clears the NetBIOS name ta- 
ble and changes the resettable maximum command and session values. 
This also does not disrupt DLC communication that may exist at the time 
of the Reset command. 


COMMANDS 

The COMMANDS (0 < = C < = 254, default = 12) parameter specifies the 
maximum number of Nebs that may be waiting for completion at one 
time. If omitted or specified as 0, the default value of 12 is used. 


DATAGRAM.MAX 

This DATAGRAM.MAX (DG=Y/N, default = N) parameter specifies that 
the maximum length datagram transmitted by NetBIOS is computed 
from the adapter’s transmit buffer size (data hold buffer or DHB) rather 
than arbitrarily using the normal 512 bytes. If specified as Y, a datagram’s 
maximum length is the transmit buffer’s size less 96 bytes (DHB Size — 
96). 

DHB.NUMBER 

The DHB.NUMBER (DN, default = NetBIOS selected) parameter speci- 
fies the number of adapter transmit buffer(s). If omitted or specified as 0, 
the value is determined by the NetBIOS device driver. 


DHB.SIZE 

The DHB.SIZE (0 or 200 <= DS <= 9999, default = NetBIOS selected) 
parameter specifies the size of the adapter’s transmit buffer(s) data hold 



52 


Part I: Introduction to NetBIOS 


buffer(s) or DHB(s). If omitted or specified as 0, the value is determined 
by the NetBIOS device driver. 


DLC.MAXIN 

The DLC.MAXIN (1 <= MI <= 9, default = 1) parameter specifies the 
MAXIN value for all NetBIOS device driver link stations. If omitted or 
specified as 0, the default value of 1 is used. 


DLC.MAXOUT 

The DLC.MAXOUT (1 <= MO <= 9, default = 2) parameter specifies the 
MAXOUT value for all NetBIOS device driver link stations. If omitted or 
specified as 0, the default value of 2 is used. 


DLC.RETRY.COUNT 

The DLC.RETRY.COUNT (1 <= RC <= 255, default = 8) parameter de- 
termines the number of retry attempts to be made by the adapter’s LLC 
code. If omitted or specified as 0, the default value of 8 is used. 


DLC.Tl 

The DLC.Tl (DLC. tee-one) (0 < = T1 < = 10, default = 5) parameter deter- 
mines the value of the T1 (response) timer in the adapter’s LLC code. If 
omitted or specified as 0, the default value of 5 is used. For more informa- 
tion on the response timer, consult the Token-Ring Technical Reference 
Manual. 


DLC.T2 

The DLC.T2 (0 < = T2 < = 11, default = 2) parameter determines the value 
of the T2 (receiver acknowledgment) timer in the adapter’s LLC code. If 
the value is 11, the T2 timer function is not used. If omitted or specified 
as 0, the default value of 2 is used. For more information on the receiver 
acknowledgment timer, consult the Token-Ring Technical Reference 
Manual. 
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DLC.TI 

The DLC.TI (DLC. tee-eye) (0 < = TI < = 10, default = 3) parameter deter- 
mines the value of the Ti (inactivity) timer in the adapter’s LLC code. If 
omitted or specified as 0, the default value of 3 is used. For more informa- 
tion on the inactivity timer, consult the Token-Ring Technical Reference 
Manual. 


ENABLE 

The ENABLE (E, positional parameter) parameter is the only 
DXMTOMOD.SYS positional parameter, and must be the first parameter 
if it is present and can be abbreviated E. The ENABLE parameter should 
be present when the host PC has an asynchronous communication 
adapter that is operating at “high-speed” (a speed equal to or greater than 
1,200 bits per second according to IBM’s field support representatives). 
The effect of this parameter, when present, is a potential “loss in perfor- 
mance” according to the DXMINFO.DOC documentation. 


EXTRA.SAPS 

The EXTRA.SAPS (0 <= ES <= 99, default = 0) parameter requests that 
the NetBIOS device driver obtain additional SAPs when it implicitly 
opens the adapter by first attempting to execute a command before the 
adapter is open. These SAPs are not used by the NetBIOS device driver. If 
omitted or specified as 0, no additional SAPs are requested. 


EXTRA.STATIONS 

The EXTRA.STATIONS (0 <= EST <= 99, default = 0) parameter re- 
quests the NetBIOS device driver to obtain additional link stations when 
it implicitly opens the adapter. These link stations are not used by the 
NetBIOS device driver. If omitted or specified as 0, no additional stations 
are requested. 


NAMES 

The NAMES (0 < = N < = 254, default = 17) parameter specifies the maxi- 
mum number of NetBIOS names that may exist in the NetBIOS name ta- 
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ble, including the universally administered address in the case of the 
Token-Ring. If omitted or specified as 0, the default value of 17 is used. 


OPEN.ON.LOAD 

If the OPEN.ON.LOAD (0=Y/N, default = Y) parameter is specified as Y, 
the NetBIOS device driver opens the adapter at load time during CON- 
FIG.SYS processing. This eliminates the delay caused by an adapter open 
when the first Neb is subsequently issued. If omitted, the default value of 
Y is used. 


RECEIVE.BUFFER.SIZE 

The RECEIVE.BUFFER.SIZE (R, default = NetBIOS selected) parameter 
specifies the size of the adapter’s receive buffers. If omitted or specified 
as 0, the value is determined by the NetBIOS device driver. 


REMOTE.DATAGRAM.CONTROL 

The REMOTE.DATAGRAM.CONTROL (RDC=Y/N, default = N) parame- 
ter is meaningless if the REMOTE.NAME.DIRECTORY (RND) (0 <= RND 
< = 255) parameter is omitted or specified as 0. 

If specified as Y, Send Datagram also uses the remote name directory 
for transmitting to remote nodes. If omitted or specified as N, Send 
Datagram does not use the RND. 


REMOTE.NAME.DIRECTORY 

If omitted or specified as 0, all Calls, Status Queries, and Send Datagrams 
are broadcast to all NetBIOS nodes, as in previous levels of NetBIOS. 

If a nonzero value is coded, the RND value specifies the number of 
remote names that may be saved by the local node. Note, the minimum 
number of name entries is 4 and the value of 4 is used if it is specified as 1, 
2, or 3. After the local station has located a remote name, the remote 
node address is saved in the remote name directory. 

Subsequent Calls, Status Queries, and Send Datagrams to that name 
are to the specific node rather than broadcast to all nodes. Issuing a Find 
Name command with a receive buffer-length of zero forces a remote name 
directory update when there is a failing bridge in the transmission path. 
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RESET. VALUES 

If specified as Y, the RESET.VALUES (RV=Y/N, default = N) parameter 
has two options. 

When the number of sessions is specified as 0 in a subsequent Reset, 
the default is the SESSIONS value rather than the normal default value of 
6. When the number of commands is specified as 0 in a subsequent Re- 
set, the default is the COMMANDS value rather than the normal default 
value of 12 . 

If omitted or specified as N, RESET works as it does in earlier releases 
of NetBIOS. 


RING.ACCESS 

The RING.ACCESS (0 <= RA <= 3, default = 0) parameter specifies a To- 
ken-Ring adapter’s ring access priority for NetBIOS device driver mes- 
sages. Higher numbers indicate a higher priority. If omitted or specified 
as 0, the default value of 0 is used. 


SESSIONS 

The SESSIONS (0 < = S < = 254, default = 6) parameter specifies the max- 
imum number of NetBIOS sessions that may be defined. If omitted or 
specified as 0, the default value of 6 is used. 


STATIONS 

The STATIONS (0 <= ST <= 254, default = 6) parameter specifies the 
maximum number of NetBIOS link stations that may be defined. If omit- 
ted or specified as 0, the default value of 6 is used. 


TRANSMIT.COUNT 

The TRANSMIT.COUNT (1 <= TC <= 10, default = 6) parameter speci- 
fies the number of times queries (Call, Remote Adapter Status Query, Add 
Name, Add Group Name, and Find Name) are transmitted. If omitted or 
specified as 0, the default value of 6 is used. 
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TRANSMIT.TIMEOUT 

The TRANSMIT.TIMEOUT (0 <= TT < = 20, default = 1) parameter spec- 
ifies the number of half-second intervals between transmission of que- 
ries (Call, Remote Adapter Status Query, Add Name, Add Group Name, 
and Find Name). If omitted or specified as 0, the default value of 1 is used 
for a half-second interval. 


DLC.MAXIN, DLC.MAXOUT, DLC.Tl, and DLC.T2 Relationship 

DLC.MAXIN is the number of frames a local link station receives before 
issuing an acknowledgment. The DLC.T2 timer specifies how long the 
receiving LLC component waits before sending the acknowledgment. If 
DLC.MAXIN is five and the local link station has received two frames, 
LLC acknowledges the two received frames when DLC.T2 expires. 

The DLC.MAXOUT specifies the number of frames a local link sta- 
tion sends before expecting an acknowledgment. The DLC.Tl timer 
specifies how long the transmitting LLC component waits for this ac- 
knowledgment. If DLC.Tl expires before an acknowledgment, the link 
station enters checkpointing which causes a sequence-information ex- 
change and network integrity validation by the link stations. 

The DLC.MAXOUT and DLC.MAXIN default values of 2 and 1, re- 
spectively, allow NetBIOS and LLC to operate in maximum parallel 
mode. A transmitting link station sends two back-to-back frames to a re- 
ceiving link station. The receiving station receives the first frame and im- 
mediately acknowledges it. Typically, by the time the second frame is 
transmitted, the acknowledgment for the first has arrived. This allows 
maximum utilization of the network. 

IBM provides a wide spectrum of LAN adapters. Combined with the 
IBM LAN Support Program’s versatility, IBM’s LAN system offerings pro- 
vide a significant degree of isolation from the underlying hardware sup- 
port, including LAN media. This allows users to select the hardware and 
topology best suited to their requirements, confident that their programs 
will function correctly independent of their specific hardware choices. 
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NetBIOS Relationships to Other IBM 

Products 


There is a common misconception that NetBIOS requires some version 
of PC-DOS. Since NetBIOS operates on UNIX-based operating systems, 
this is clearly false. Moreover, if you use an IBM PC Network LANA 
adapter, you can write NetBIOS programs that execute on PC-DOS 1.0. 


IBM PC-DOS Version Requirements 

PC-DOS 3.1, and later PC-DOS versions, contain LAN considerations for 
the PC-DOS redirector. The redirector provides PC-DOS services neces- 
sary for the operation of the IBM PC LAN Program. REDIR.EXE module 
actually provides the redirector services and is an IBM PC LAN Program 
component. 


IBM PC LAN Program Considerations 

The IBM PC LAN Program expects to be the first NetBIOS user of a LAN 
adapter. If there are any existing sessions or names registered in the Net- 
BIOS name table, the Program will not provide network services and ter- 
minates operation. This happens because the Program may reset a LAN 
adapter in an attempt to increase the maximum number of sessions and 
pending commands. 

Appendix B of the IBM PC Local Area Network Program User's 
Guide contains a list of additional restrictions that must be observed by 
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coexisting NetBIOS applications if the IBM PC LAN Program is to operate 
correctly in a server configuration. 


Coexistence Restrictions 

NetBIOS applications may need to determine if the IBM PC LAN Program 
is operating. If it is, the applications should observe the following con- 
siderations as mentioned in the Guide. 

• They should not use all the available sessions and pending com- 
mands, because the IBM PC LAN Program needs some. 

• They should not issue a NetBIOS Reset command because this 
removes the names the IBM PC LAN Program has added to the 
NetBIOS name table. 

• They should not use any of the names added to the NetBIOS name 
table by the IBM PC LAN Program. 

• They should not use the Receive-Any-for-Any Name command be- 
cause the IBM PC LAN Program needs to receive its messages. 

• They should not use the values OOh to 1 Fh for the l6th byte value 
in NetBIOS names because these are reserved for the IBM PC LAN 
Program. Application programmers are encouraged to use a blank 
(20h) as the l6th character in NetBIOS Names. 

• They should carefully reflect appropriate captured hardware and 
software interrupts and do so in a disabled state to simulate correct 
entry into the IBM PC LAN Program. 

• To avoid overlaid data problems, destroyed FATs, and destroyed 
directories, they must not do direct disk or diskette accesses to 
write data. 

• They should not directly program the display controller (e.g., 
6845) to avoid the possibility of the IBM PC LAN Program’s im- 
properly restoring the display settings. The controller settings 
should be changed only with application BIOS calls. 

• They should not use the NetBIOS Receive Broadcast Datagram 
command. Application designers are warned that using Receive 
Broadcast Datagram “will probably result in PC LAN or applica- 
tion failures that will require the user to reset (Ctrl-Alt-Del) the ma- 
chine.” Application designers are advised to use plain datagrams 
sent to group names if necessary. 

• Where appropriate, they should use DOS file-handle functions 
with sharing modes and avoid using FCBs because FCBs do not 
support file sharing or locking functions. If this is not possible. 
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applications should not construct their own FCBs, change FCB re- 
served areas, or close the FCB and continue to use it as though it 
were still open. The last restriction includes saving an FCB in a file 
for use at another time. Moreover, to insure data integrity, applica- 
tions should periodically close and reopen files that are accessed 
via FCBs. 

• They should use the PC-DOS Create Unique File function (INT 
21h AH=5Ah) to create temporary files. To avoid file contention 
and collisions in multiuser environments, they should not use 
fixed names for temporary files. 

• They should use the PC-DOS Create New File function (INT 21h 
AH=5Bh) to create a file instead of simply creating one to see if it 
already exists. 

• To avoid “unpredictable problems” they should not change the 
timer tick rate from its natural 18.2 times per second rate. 

For more information, consult Appendix B of the Guide. 


Detecting the Program 

The IBMLANPG.C sample program in Listing 6-1 illustrates the proper 
way a program should determine whether the IBM PC LAN Program is 
installed. The application should first check that the PC-DOS version is 
3.10 or later, then check to see if the Program is installed. If so, the appli- 
cation can request the machine name that the Program is using. 

The machine name is returned as a 15-character name, padded at the 
end with blanks. A l6th byte holds an ASCII zero. In reality, the l6th byte 
of the machine name in the NetBIOS name table is a blank. For more de- 
tails, check the Guide and the PC-DOS Technical Reference Manual, 
which documents the Get Machine Name function. 

Listing 6-1. IBMLANPG.C 

^define LINT_ARGS 

#incLude <dos.h> 
ifinclude <stdio.h> 

#include "netbiosZ.h" 

#if defined(LINT_ARGS) 
extern int maintint argc.char * *argv); 
extern int CheckDosVersion(void); 
extern void CheckForlbmLanPrograin(void); 
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Listing 6-1. (cont.) 


extern 

void GetMachineName(void) 

extern 

void Logo (void); 


#endi f 



#def ine 

D0S_INT_21 

0x21 

#def ine 

D0S_INT_2A 

0x2A 

#def ine 

D0S_INT_2F 

0x2F 

#def ine 

PC_LAN_PGM_CHECK 

0x8800 

#define 

DOS_FETCH_VERSION 0x30 

#define 

GET_MACHINE_NAME 

OxSEOO 

#def ine 

REDIRECTOR_FLAG 

0x0008 

#def ine 

RECEIVER_FLAG 

0x0080 

#def ine 

MESSENGER_FLAG 

0x0004 

#def ine 

SERVER_FLAG 

0x0040 

int mainCargc, argv) 


int argc; 


char *argv[]; 






LogoO ; 

if (CheckDosVersionO) 

CheckForlbmLanProgramO ; 

printf ("\n\nProgram ending. . .\n"); 

return 0; 

> 

int CheckDosVersionO 
{ 

union REGS InRegs, OutRegs; 

InRegs.h.ah = DOS_FETCH_VERSION; 

int86(DOS_INT_21 , &InRegs, SOutRegs); 

printf ("\n\nThe PC-DOS Version is %u.%u... ", 

OutRegs. h. at, OutRegs. h. ah) ; 


if (OutRegs. h. at < 3) /* check the major version number */ 
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Listing 6-1. (cont.) 


return FAILURE; 

if (OutRegs.h.ah < 10) /* check the minor version number */ 

return FAILURE; 

InRegs.h.ah = 0; 

int86(D0S__INT_2A, &InRegs, &OutRegs); 
if (OutRegs.h.ah != 0) 

printf (''\n\nThe INT 2A NetBIOS interface is avai table. ..") ; 
else 

printf ("\n\nThe INT 2A NetBIOS interface is not avai table. .. \x07") ; 
return SUCCESS; 


void CheckForlbmLanProgramO 
USGC temp; 

union REGS InRegs, OutRegs; 

InRegs.x.ax = PC_LAN_PGM^CHECK; 
int86(DOS_INT_2F, SlnRegs, &OutRegs); 
if (OutRegs. h. at == 0) { 

printf ("\n\nThe IBM PC LAN Program is not instal ted. . .\x07") ; 
return; 

> 

printf ("\n\nThe IBM PC LAN Program is installed "); 
printfC'and operating as a "); 

temp = OutRegs. h.bt & (REDIRECTOR_FLAG ’ RECEIVER_FLAG j 
MESSENGER_FLAG j SERVER_FLAG) ; 

/* The order of testing is important because 
the bit settings are cumulative as are the 
configurations. 

*/ 


if (SERVER_FLAG & temp) 
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Listing 6-1. (cont.) 

printf ("Server.”) ; 
else if (MESSENGER_FLAG & temp) 
printf ("Messenger.") ; 
else if (RECEIVER_FLAG & temp) 
printf ("Receiver.") ; 
else if (REDIRECTOR_FLAG & temp) 
printf ("Redi rector.") ; 

else -C 

printf ("and operating in an unknown configuration. \x07") ; 
return; 

> 

GetMachi neNameO ; 

> 

void GetMachineNameO 

struct SREGS SegRegs; 

union REGS InRegs, OutRegs; 

char Buffer[16], far *BufferPtr = Buffer; 

InRegs. X. ax = GET^MACHINE_NAME; 

SegRegs. ds = FP_SEG(BufferPtr) ; 

InRegs. x.dx = FP_OFF(BufferPtr) ; 

int86x(D0S_INT_21 , &InRegs, &0utRegs, &SegRegs); 

if (Out Regs. h.ch != 0) { 

printf ("\n\nThe machine name is ==>%s<== ", Buffer); 
printf ("\n\nThe machine name’s NetBIOS Name Number is %u." 

, OutRegs. h. cl) ; 

> else 

printf ("\n\nThe machine name is not defined..."); 


void LogoO 

printf ("\nIBM Local Area Network Program Presence Test Program"); 
printf ("\n© Copyright 1988 W. David Schwaderer "); 
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LAN Data Integrity and Security 


This material merits its own discussion because the issues of LAN data 
integrity and security are becoming critical as LANs become more perva- 
sive within business environments. 


LAN Data Integrity 

The good news is that LAN communication is typically very reliable. 
However, some LAN adapters do not have Cyclic Redundancy Checking 
(CRC) for message transmission and reception verification, and some do 
not have parity checking for onboard adapter memory. 

The chilling fact is that if sections of a network’s transmission path 
do not have these or comparable facilities, end-to-end data integrity can- 
not be guaranteed without some extra application programming effort. 
It may be worthwhile to check with your potential vendor to see if your 
LAN has sufficient data integrity features to satisfy your requirements. 


LAN Data Security — A Word to the Wise 

LANs provide all the data security that cordless telephones provide their 
users. Just as a cordless phone broadcasts conversations for passers-by 
and neighbors to monitor, all LAN communication is broadcast to all LAN 
adapters. 

The adapter determines whether the data enters the workstation’s 
memory or is simply discarded. Given enough guidance from a deter- 
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mined programmer, many LAN adapters can be coaxed into what is re- 
ferred to as promiscuous mode, receiving all LAN-transmitted data for 
subsequent distribution to and leisurely review by affluent or otherwise 
interested third parties. Consider the following IBM statements.. 


IBM Statement 1 

Above the copyright notice, the Token-Ring Network PC Adapter Tech- 
nical Reference Manual states: 

Note; This product is intended for use within a single establish- 
ment and within a single, homogeneous user population. For 
sensitive applications requiring isolation from each other, man- 
agement may wish to provide isolated cabling or to encrypt the 
sensitive data before putting it on the network. 

Remember that achieving, not to mention maintaining, user population 
homogeneity could present a challenge. 


IBM Statement 2 

The IBM NetBIOS Application Development Guide Introduction states: 

It is the responsibility of the operating system or application pro- 
gram to make sure that data or devices are secure on the network 
as network security is not built into the NetBIOS. 


Permanent Node Name Capers 

You might suppose you can use an adapter’s permanent node name to 
identify workstations involved in communication activities. However, 
unfriendly LAN users may alter their locally administered name or even 
covertly exchange LAN adapters among workstations. 

This potentially allows a user to obtain a coveted permanent node 
name and subsequently “impersonate” other LAN users authorized with 
special LAN privileges by virtue of their permanent node names. Such 
privileges might include using the LAN to silently eavesdrop on other 
LAN workstation activities and inspection or manipulation of sensitive 
files — all unobtrusively from behind closed doors. 
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Thus, while IBM LAN adapter initialization procedures and support- 
ing software guarantee that a node’s permanent node name or locally ad- 
ministered ID is unique on a given LAN, be vigilant when you use adapter 
numbers as the only mechanism for user identification or LAN-user priv- 
ilege administration. 

You may not know who is really using a privileged permanent node 
name. While you might want to keep these numbers confidential from 
users, this is generally a futile effort against determined or sophisticated 
LAN penetrations. 


The Uneasy Conclusion 

As of this writing, portable LAN monitors are commercially available that 
can selectively or indiscriminately record and display everything trans- 
mitted on an Ethernet and IBM Token-Ring LAN. Though they are some- 
what expensive, you should not discount their eventual use within your 
establishment. 

If you would not project your spreadsheets, personal mail, financial 
data, etc., on a neighborhood drive-in theater’s screen, you would be 
well advised to consider encrypting your data before transmitting it on a 
LAN. 
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General Support Programming 


Our first NetBIOS program resets an adapter that is assumed to be con- 
trolled by the IBM LAN Support Program. Examine this program in detail 
because it presents many NetBIOS programming principles used, but not 
discussed, in later programs. If you only study one program completely, 
this should be it. Note that all programs assume compatibility with 
Microsoft Corporation’s C 5.0 compiler. 

First note the #define LINT_ARGS statement. All programs contain 
this statement to include subsequent function prototype statements in 
the compilation. The compiler produces these statements when invoked 
with the /Zg parameter. (Redirecting the compiler output to a file allows 
the generated prototypes to be included in the source listing or separate 
header file.) All program function declarations observe pre-ANSI X3J11 
conventions but can easily be replaced by modified function prototype 
statements if supported by your compiler. 

Second, note the test for the adapter in the main{ ) routine. To elimi- 
nate repetition, all subsequent program listings do not include this test. 

Finally, note that the netbios2.h include file listed in Appendix A de- 
fines all symbolic values (e.g., SUCCESS, MAX_ADAPTER_NUMBER, 
etc.). 


The NetBIOS RESET Sample Program 

The RESET.C program in Listing 8-1 resets a NetBIOS adapter, and ac- 
cepts three integer parameters. In order, they are: 

1 . the number of the adapter to reset (0 or 1) 
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2. the maximum session count (0 to 254) 

3. the maximum pending command count (0 to 255) 

If no parameter or an incorrect parameter is entered, the program dis- 
plays a usage message. Note, the actual maximum allowable values for 
the session and command counts varies and may be controlled by IBM 
LAN Support Program /S and /C parameter values, respectively Exceed- 
ing the ceiling values specified as IBM LAN Support Program parameter 
values forces NetBIOS to compute its own values. To dynamically deter- 
mine these ceiling values, a program must issue an Adapter Status re- 
quest. 


Listing 8-1. RESET.C 

#define LINT_ARGS 

^include <dos.h> 

#incLude <stdio.h> 

^include "netbiosZ.h'* 

#if defined (LINT_ARGS) 

extern int mainCint argc,char * *argv); 

extern void Logo(void); 

extern int CheckDosIVs(void); 

extern int IssueInvalidNetbiosRequest (void) ; 

extern int Edi tParmsCint argc,char * *argv); 

extern void ResetAdapter (unsigned int AdapterNumber, 

unsigned int SessionCount , 
unsigned int CommandCount) ; 
extern void CLearNcb(struct Neb *NcbPtr); 
extern void NetbiosRequest (struct Neb *NcbPointer) ; 
extern void AnaLyzeResetError(int ResetErrorCode) ; 
extern void ExpLain(void); 
extern void Exi tNow(void) ; 

#endif 

struct Neb ResetNcb; 

struct SREGS SegRegs; 

int main(argc, argv) 
int arge; 
char ★argvC]; 
i 
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Listing 8-1. (cont.) 


LogoO ; 

if (( ! CheckDosIVsO) [| ( ! IssueInvalidNetbiosRequest ())) -C 

printf ("\n\nNetBIOS not present .. .program ending. . .\n\n\x07") ; 
Exi tNowO ; 

> 

if ( ! Edi tParmsCargc, argv)) { 

ExpLainO ; 

ExitNowO ; 

> else ResetAdapter (atoi (argvCI ]) , 
atoi (argvC23) , 
atoi (argv[3])) ; 

return 0; 

> 

void LogoO 

printf ("\n NETBIOS Adapter Reset Sample Program”); 

printf (”\n © Copyright 1988 W. David Schwaderer”) ; 

> 

^define D0S_INT_21 0x21 
^define DOS_FETCH^IV 0x35 

int CheckDosIVsO 

union REGS InRegs, OutRegs; 
struct SREGS SegRegs; 

InRegs. h. ah = DOS_FETCH_IV; 

InRegs. h.al = NetbiosIntSC; 

int86x(D0S_INT_21 , SlnRegs, SOutRegs, &SegRegs); 

switch (SegRegs. es) C 

case 0x0000 : return FAILURE; 
break; 

case OxFOOO : return FAILURE; 
break; 

default : return SUCCESS; 

break; 
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Listing 8-1. (cont.) 


> 

> 

int IssueInvalidNetbiosRequest () 
struct Neb PresenceNcb; 

C learNcbC&PresenceNcb) ; 

PresenceNcb. NebCommand = NETBIOS_INVALID_COMMAND; 

NetbiosRequest C&PresenceNcb) ; 

if (PresenceNcb. NebRetCode == (USGC) 0x03) 
return SUCCESS; 
else' 

return FAILURE; 

> 

int Edi tParmsCarge, argv) 
int arge; 
char *argvC]; 
i 

int ReturnFLag = SUCCESS; 
if (arge != 4) { 

printf ('’\n\n\x07Incorrect number of parameters..."); 
return FAILURE; 

> 

if ((atoi(argv[1]) < 0) H (MAX_ADAPTER_NUMBER < atoi (argvH ] ) )) { 
printf ("\n\n\x07Incorrect adapter-number parameter value (%d)...", 

atoi (argvll])); 

ReturnFlag = FAILURE; 

> 

if ((atoi (argv[2]) < 0) 1 1 (MAX_SESSION_COUNT < atoi (argvC2]))) i 
printf ("\n\n\x07Incorrect session-count parameter value (%d)...", 

atoi (argv[2] )) ; 

ReturnFlag = FAILURE; 

> 

if ((atoi(argv[3]) .< 0) H (MAX_C0MMAND_.C0UNT < atoi (argv[3] ) ) ) { 
printf ("\n\n\x07Incorrect command-count parameter value (%d)...", 
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Listing 8-1. (cont.) 


ReturnFLag = FAILURE; 

> 


atoi (argv[3])) ; 


if (ReturnFLag == FAILURE) 
return FAILURE; 

if (atoi (argv[2]) == 0) { 
printf ("\n\nWarning. . .") ; 

printf ("NetBIOS selects the session count value. . .\x07") ; 


if (atoi (argv[3] ) == 0) -C 
printf ("\n\nWarning. . ."); 

printf ("NetBIOS selects the command count value. . .\x07") ; 


return SUCCESS; 

> 


void ResetAdapter(AdapterNumber, SessionCount , CommandCount) 
unsigned AdapterNumber, SessionCount, CommandCount; 

printf ("\n\nNETBIOS adapter %d reset parameters ==>", AdapterNumber) ; 
printf (" %d session%s and %d command%s. . 

SessionCount, (SessionCount == 1) ? "" : "s", 

CommandCount, (CommandCount == 1) ? "" : "s"); 


printf ("\n\nPlease wait for the adapter to reset..."); 
ResetNcb.NcbCommand = NETBIOS RESET WAIT ONLY: /* reset command code */ 


ResetNcb.NcbLanaNum = AdapterNumber; 
ResetNcb.NcbLsn = SessionCount; 
ResetNcb.NcbNum = CommandCount; 

NetbiosRequest (SResetNcb) ; 


/* adapter number ♦/ 
/* concurrent session count */ 
/* concurrent command count */ 

/* Neb was already zero */ 


if ( IResetNcb.NcbRetCode) { 

printf ("\n\nThe return code was %x.\n", ResetNcb.NcbRetCode) ; 

> 

else { 

printf ("\n\n\x07The return code was %x ", ResetNcb.NcbRetCode); 
Ana lyzeReset Error (ResetNcb.NcbRetCode) ; 
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Listing 8-1. (cont.) 

pn'ntf ("\n") ; 

> 

> 

void ClearNcb(NcbPtr) 
struct Neb *NcbPtr; 

int i; 
char *CharPtr; 

CharPtr = (char *) NcbPtr; 

for ( i = 0; i < si zeof (ZeroNcb) ; i++ ) 
*CharPtr++ = 0x00; 

> 


void NetbiosRequest (NebPointer) 
struct Neb *NcbPointer; 

union REGS InRegs, OutRegs; 

struct Neb far *NcbPtr = (struct Neb far *) NebPointer; 

SegRegs.es = FP_SEG(NcbPtr) ; 

InRegs. x.bx = FP_OFF(NcbPtr) ; 

int86x(NetbiosInt5C, SlnRegs, &0utRegs, &SegRegs); 

> 

void AnaLyzeResetError(ResetErrorCode) 
int ResetErrorCode; 

if (ResetErrorCode == 0x03) -C 

printf ("[invalid command code]"); 
return; 

> 

if (ResetErrorCode == 0x23) *C 

printf ("[adapter not installed]"); 
return; 

> 

if ((0x3F < ResetErrorCode) && (ResetErrorCode < 0x50)) -C 

printf ("[unusual network condition -or- unacceptable ring-status]"); 
return; 
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Listing 8-1. (cont.) 


> 

if (0x4F < ResetErrorCode) { 

printf ("[adapter malfunction -or- "); 

printf ("Adapter/PC unusual condition/error ]"); 

return; 

> 

printf ("[undocumented error] \x07") ; 

> 

void ExplainO 

printf ("\n\nusage: reset adapter-number session-count command-count"); 
printf ("\n\n where: 0 <= adapter-number <= %d", MAX_ADAPTER_NUMBER) ; 
printf ("\n 0 <= session-count <= %d", MAX_SESSION_COUNT) ; 

printf ("\n 0 <= command-count <= %d", MAX_COMMAND_COUNT) ; 

> 

void ExitNowO 

printf ("\n\nEnding RESET because of parameter input errors. .. \n") ; 
exitd); 

> 


Support Routines 

The main( ) routine first invokes Logo( ) which displays a logo. It then 
calls CheckDosIVs( ) and IssueInvalidNetbiosRequest( ) to verify that 
NetBIOS is present. Part I discusses these tests in more detail. 

If NetBIOS is not present, the program terminates after issuing an 
acerbic comment. Otherwise, control passes to EditParms( ) which 
checks the command-line parameters. 

EditParms( ) 

The various EditParms( ) routine checks are: 

1 . The parameter count should be four. 

2 . The adapter number should have a nonnegative value of zero or a 
value not greater than MAX_ADAPTER_NUMBER. 
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3 . The requested number of sessions should be less than the maxi- 
mum allowable (MAX_SESSION_COUNT). 

4. The requested number of maximum outstanding commands al- 
lowable should be less than the maximum allowable (MAX_ 
COMMAND_COUNT). 

If the session or command value is zero, a warning is presented to the 
user stating that NetBIOS will compute the parameter value. 

If the parameters are not acceptable, main( ) invokes Explain( ) to dis- 
play the appropriate parameter values and then exits by invoking Exit- 
Now( ). Otherwise, the parameters are acceptable and main( ) invokes the 
ResetAdapter( ) routine to reset the adapter. 


ResetAdapter( ) 

The ResetAdapter( ) routine first displays the adapter number, session 
count, and pending command count values it uses in its Reset command. 
Because the NetBIOS reset may take a few seconds, it issues a request for 
user patience. Whether it actually delays the few seconds is controlled 
by the IBM LAN Support Program CR parameter discussed in Part I . 

ResetAdapter( ) completes the required fields in the Neb structure 
named ResetNcb located near the top of the listing, and invokes Netbios- 
Request( ) to issue the request. If NetBIOS is not present in the machine, 
the machine generally freezes at this point. Note that the symbolic value 
of the Reset command code (NETBIOS_RESET_WAIT_ONLY) clearly 
indicates that a no- wait version of the command does not exist. 

After NetBIOS returns, ResetAdapter( ) inspects the return code. If it 
is zero, then ResetAdapter( ) displays a success message and returns to 
main( ) which then exits. Alternatively, ResetAdapter( ) displays the non- 
zero return code and invokes AnalyzeResetError( ) to display an English 
explanation before it exits. 


Analy2eResetError( ) 

Properly analyzing error codes is a challenge because different IBM Net- 
BIOS implementations provide different adapter-dependent error codes. 
The error code analysis presented in AnalyzeResetError( ) is for errors 
applying to the PC Network LANA NetBIOS. Note that IBM Token- Ring 
4Xh and FXh error codes reflect an unacceptable ring status and an 
adapter/PC unusual condition/error, respectively. Clearly, the applicabil- 
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ity of an unacceptable ring status error code to a CSMA/CD PC Network 
adapter controlled by the IBM LAN Support Program is inappropriate. 
Thus, you must refer generally to the adapter’s NetBIOS documentation 
before you can correctly interpret error codes. 


Why Didn’t ResetNcb Get Zeroed by ClearNcb( )? 

Because of its position in the program, ResetNcb is located in static stor- 
age, which is always initialized to zeros. Thus, ResetNcb does not require 
zeroing before ResetAdapter( ) uses it. However, if ResetNcb is a Reset- 
Adapter( ) automatic variable or was used in a previously completed Net- 
BIOS command, it requires zeroing by invoking ClearNcb( ). Part I 
discusses the CIearNcb( ) and NetbiosRequest( ) routines in more detail. 


The NetBIOS Adapter Status Sample Program 

The primary challenge of any adapter status program is displaying the 
large amount of returned data. The job is significantly complicated be- 
cause different IBM versions of NetBIOS return different data or return the 
same data at different displacements within the returned information. 

For example, IBM LAN Support Program NetBIOS implementations 
return the maximum datagram packet size at offset 48 (decimal). The 
original LANA NetBIOS does not return this data at all and offset 48 re- 
sides within a reserved area for this NetBIOS version. Moreover, the IBM 
LAN Support Program returns the major NetBIOS version number at off- 
set 06 (decimal). However, the LANA NetBIOS returns the adapter 
jumper settings at offset 06 and the NetBIOS major version number at 
offset 08. 

Finally, Token-Ring adapter status data may contain extended status 
information, valid only for adapter status commands for local adapters. 
This information may also contain adapter counter information that is 
valid “only if no ring-status appendage is defined” according to the To- 
ken-Ring PC Adapter Technical Reference Manual. There is no method 
to determine whether such a ring-status appendage is defined. See Part 
IV of this book for more details. 

Because the primary purpose of this book is to teach basics, the 
Adapter Status sample program takes the simple road and illustrates a par- 
tial NetBIOS Adapter Status command applicable to adapters controlled 
by the IBM LAN Support Program. A complete general program is left as a 
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reader exercise. Note that the netbios2.h include file provides sample 
adapter status structures for both IBM adapter status formats. The IBM 
LAN Support Program format and the PC Network LANA format are Dlc- 
Status and LanaStatus structures, respectively. The PC Network II and 
II/A adapters use the DlcStatus structure. 

The main( ) Function 

The main( ) routine displays a simple logo and invokes EditArgs( ) to vali- 
date the single valid input parameter. Assuming the parameter passes the 
tests, RequestStatus( ) issues the Adapter Status command. If the com- 
mand is not successful, a complaint is displayed containing the failing 
return code and the program ends. Otherwise, DlcStatus( ) displays the 
returned adapter type and permanent node name information fields. Fi- 
nally, main( ) displays the number of NetBIOS names in the adapter Net- 
BIOS name table before exiting. Note that each name in the table requires 
18 bytes and that the minimum buffer size is 60 bytes. Since the IBM LAN 
Support Program N parameter allows a maximum of 254 names in the 
NetBIOS name table, a buffer size of 4,632 bytes (60 -f 18 X 254) is gener- 
ally required to hold all possible returned data. 


EditArgs( ) 

The Adapter Status sample program accepts one input parameter — the 
name of the adapter to provide the adapter status information. It may be a 
local or remote adapter. 

Input Parameter Name Format 

The name may be a unique name, a group name, or a permanent node 
name. A NetBIOS name generally consists of 16 arbitrary characters. 
However, the Adapter Status program does not support this because 
some characters (e.g., carriage return) cannot be specified on the PC- 
DOS command line. The permanent node name specification technique 
overcomes this limitation. 

Parameter Processing — Special Cases 

There are three special cases that are distinguished by the first character 
of the input parameter: 

1 . If the first character is a question mark (?), no name is specified 
and the program returns usage information before exiting. 
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2 . If the first character is an asterisk (*), the local adapter specified in 
the Adapter Status command’s NcbLanaNum field provides the 
data. 

3. If the first character is a backslash (\), the parameter specifies a 
local or remote adapter permanent node name. The actual format 
of the parameter is: \x.hh.hh.hh.hh.hh.hh. 


where each h represents a valid hexadecimal digit. In this case, the six 
specified bytes are appended to 10 bytes of binary zeros to create the ac- 
tual network permanent node name. Note that the length of this type 
specification is exactly 20 characters. A valid 20-character parameter is 
converted to a six-byte value invoking sscanf( ). This should produce ex- 
actly six hexadecimal characters. 

These six characters are placed in the six-element HoldNodeld char- 
acter array. After zeroing the first 10 characters of the 16-element 
HoldNetworkName character array, these six characters are then moved 
into the last six characters of the HoldNetworkName character array, 
completing the permanent node name specification later used in the 
Adapter Status command. Finally, note that NetBIOS names can use spe- 
cial characters such as the ASCII carriage return value or a binary zero 
character. However, users cannot enter such characters on the PC-DOS 
prompt line as part of a 16-character name. 

Allowing an alternate parameter length of exactly 50 characters and 
extending the switch statement logic permits general l6-character Net- 
BIOS name specifications as implied above. This is left as a straight-for- 
ward reader exercise. The format of such a parameter is: 


\x.hh.hh.hh.hh.hh.hh.hh.hh.hh.hh.hh.hh.hh.hh.hh.hh 


Parameter Processing — Normal Case 

If the parameter is not a special-case parameter, it is treated as a normal 
symbolic network name and is copied directly into the l6-element 
HoldNetworkName character array. In this case, all characters are signifi- 
cant and lowercase letters are different than uppercase letters. 

If the name has less than 16 characters, the remaining uninitialized 
HoldNetworkName array character elements are set to ASCII blanks. 
Warning! While some programs such as the IBM Token-Ring Network/PC 
Network Interconnect Program require blanks as the l6th character, arbi- 
trarily selecting blanks as a filler character value can be a significant pro- 
gramming hazard. Other programs may use different filler character 
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values resulting in name parameters that look the same on the PC-DOS 
command lines but have different NetBIOS name table values. 

Perhaps binary zeros would be more appropriate, as a filler or even 
ASCII carriage returns. The important thing is to recognize that such an 
arbitrary decision is likely inappropriate. The only alternative is to allow 
a 50-character input parameter that allows users to specify the hexadeci- 
mal value of every name character. 

DlcStatus( ) and DisplayNetbiosLevel( ) 

DlcStatus( ) in Listing 8-2 first invokes DisplayNetbiosLevel( ) to display 
the level of the NetBIOS supporting the target adapter. DisplayNetbios- 
Level( ) assumes that the IBM LAN Support Program provided the adapter 
status data, so it displays the NetBIOS level as well as the type of parame- 
ters used to initialize the DXMTOMOD.SYS device driver (NetBIOS) be- 
fore returning to the DlcStatus routine. Note that DXMINFO.DOC 
contains critical information on the data format that is incorporated in 
the netbios2.h header file. 

Like DisplayNetbiosLevel( ), DlcStatus( ) assumes the IBM LAN Sup- 
port Program provides the adapter status data, and so determines and dis- 
plays what type adapter has provided it, concluding its operation by 
displaying the permanent node name of that adapter. Note that Dlc- 
Status( ) could display much more data but a complete listing results in 
excruciatingly boring pages of printf( ) statements, so that task is left as a 
reader exercise. 


#define LINT_ARGS 


Listing 8-2. STATUS.C 


Uinc Lude 
^include 
^include 
#include 
^include 
^include 


<dos.h> 

<ctype.h> 

<stdio.h> 

<string.h> 

<process.h> 

"netbios2.h'' 


struct SREGS SegRegs; 
struct Neb StatusNcb; 

struct DLcStatus DLcData; I* LAN Support Program Status Structure */ 

unsigned char HoLdNodeIdC6]; 
unsigned char HoLdNetworkNameC16] ; 
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Listing 8-2. (cont.) 


#if defined(LINT_ARGS) 

extern int mainCint argc,char * *argv); 

extern unsigned char RequestStatus(void) ; 

extern void Di spLayDLcStatus (char * ★argv); 

extern void DisplayNetbiosLevel (void) ; 

extern void C LearNcb(struct Neb *NcbPtr); 

extern void NetbiosRequest (struct Neb ★NebPointer) ; 

extern int EditArgs(int argc,char * *argv); 

extern void Logo(void); 

extern void ExpLai n(void) ; 

extern void ExitNow(void) ; 

#endi f 

int main(argc, argv) 
int arge; 
char *argvC]; 

unsigned char temp; 

LogoO ; 

if ( ! Edi tArgs(argc, argv)) 

Exi tNowO ; 

if (temp = RequestStatusO) 

printf ("\n\nRequest status error %02Xh...\n", temp); 
else { 

Di spLayDLcStatus(argv) ; 
printf ("\n\nThere "); 

(DlcData.NameTableEntryCount == 1) ? printfC'is") : printf ("are") ; 
printf (" %u ", DLcData.NameTableEntryCount) ; 
(DlcData.NameTableEntryCount == 1) ? printf ("entry") : 
printf ("entries") ; 

printfC in the adapter Name Table."); 

> 

putchar ( ' \n' ) ; 
return 0; 

> 


unsigned char RequestStatusO 
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Listing 8-2. (cont.) 

int temp; 

char far *StatusBufferPtr = (char far *) SDlcData; 
CLearNcbC&StatusNcb) ; 

StatusNcb.NcbBuf ferOffset = (char *) FP_OFF(StatusBufferPtr) ; 
StatusNcb.NcbBufferSegment = (unsigned) FP_SEG(StatusBufferPtr) ; 

StatusNcb.NcbCommand = NETBIOS_ADAPTER_STATUS; 

StatusNcb.NcbLength = sizeof (DlcData) ; 

StatusNcb.NcbLanaNum = 0; 

for (temp = 0; temp < 16; temp++) 

StatusNcb.NcbCal LNameCtemp] = HoldNetworkNameCtemp] ; 

Netbi osRequest (&StatusNcb) ; 

return StatusNcb.NcbRetCode; 

> 

void Di splayDLcStatus(argv) 
char *argv[]; 

int i, j; 

Di spLayNetbi os Level 0 ; 

/* Adapter Type */ 

switch (DlcData. LanAdapterType) { 
case TOKEN_RING_ADAPTER : 

printf ("Token Ring Adapter."); 
break; 

case PC_NETWORK^ADAPTER : 

printfC'PC Network Adapter."); 
break; 

default ; 

printf ("Unknown Adapter. . .\x07") ; 
break; 

> 


/*• 


*/ 


Permanent Node Name 
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Listing 8-2 . (cont.) 

printf ("\n\nAdapter Permanent Node Name: ”); 

for (i = 0; i < si zeof (DLcData.PermanentNodeName) ; i++) 
printf <"%02X", ((unsigned char) OxFF) & DLcData.PermanentNodeNameCi ]); 

> 

void Di splayNetbiosLevel () 

•C 


/* — NETBIOS Version Information — */ 


printf ("\n\nUsing NetBIOS Version %u.%u ", 

(DLcData.MajorVersionNumber & VERSION^MASK) , 
(DlcData.MinorVersionNumber & VERSION_MASK) ) ; 


switch (DlcData.MinorVersionNumber & PARM_MASK) { 
case 0LD_PARMS : 

printf ("with \"oLd\""); 
break; 


> 


case NEW_PARMS : 

printfC'with \"new\""); 
break; 

default : 

printf ("?? ~ Undefined input parameter format\x07") ; 


printf (" parameters on a "); 

> 


void ClearNcb(NcbPtr) 
struct Neb *NcbPtr; 

T 

i nt i ; 
char *CharPtr; 

CharPtr = (char *) NcbPtr; 

for ( i = 0; i < si zeof (ZeroNcb) ; i++ ) 
*CharPtr++ = 0x00; 

> 


void NetbiosRequest (NebPointer) 
struct Neb *NcbPointer; 
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Listing 8-2. (cont.) 

union REGS InRegs, OutRegs; /* defined in dos.h */ 
struct Neb far ★NcbPtr = (struct Neb far *) NebPointer; 

segreadC&SegRegs); 

SegRegs.es = FP_SEG(NcbPtr) ; 

InRegs. x.bx = FP_OFF(NcbPtr) ; 

int86x<NetbiosInt5C, &InRegs, &OutRegs, SSegRegs); 

> 

int EditArgsCargc, argv) 
int arge; 
char ★argvC]; 

char c; 
int temp; 

char *NodeNamePointer; 

if (arge < 2) { 

ExpLainO ; 
return FAILURE; 

> 

if (arge > 2) { 

printf ("\nToo many parameters. . .\n"); 

ExpLainO ; 
return FAILURE; 

> 

switch (*argv[1]) { 
case '?* : 

ExpLainO ; 
return FAILURE; 
break; 


case 'W : 

if (str Len(argv[1 ]) != 20) { 

printf ("\nParameter has the incorrect Length."); 
printf ("\nShouLd be 20 characters Long."); 
return FAILURE; 


> 
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Listing 8-2. (cont.) 

temp = sscanf (argvCI ] , ''\\x.%2x.%2x.%2x.%2x.%2x.%2x", 
SHoLdNodeldCO], &HoLdNodeId[1 ] , 
&HoLdNodeId[2], &HoLdNodeIdC3] , 
&HoLdNodeId[4] , &HoLdNodeIdC5] ) ; 


if (temp != 6) -C 

printf (*'\nscanf () problem with input parameter..."); 
printf ("\nplease clean up your input parameter..."); 
printf ("\nformat ==> Wx.HH.HH.HH.HH.HH.HH") ; 
printf ("\nparameter ==> %s", argvH]); 
return FAILURE; 

> 

printf ("\nRequesting status for network node \\x."); 
p r i n t f ("%02X . %02X . %02X . %02X . %02X . %02X" , 

HoldNodeldCO] & OxOOFF, HoldNodeldd] & OxOOFF, 
HoldNodeId[23 & OxOOFF, HoldNodeId[3] & OxOOFF, 
HoldNodeldCA] & OxOOFF, HoldNodeldCS] & OxOOFF); 

for (temp = 0; temp < 10; temp++) { 
HoldNetworkNameCtemp] = 0x00; 

> 

for (temp = 0; temp < 10; temp++) { 
HoldNetworkNameCtemp+10] = HoldNodeldCtemp] ; 

> 

break; 


default: 

if (str len(argv[1 ]) > 16) { 

printf ("\nParameter has the incorrect length."); 
printf ("\nShould be one to sixteen characters long."); 
return FAILURE; 

> 

for (temp = 0, NodeNamePointer = argvEI]; 

(temp <16) && (c = *NodeNamePointer) ; 
temp++, NodeNamePointer++) { 

HoldNetworkNameCtemp] = c; 

> 

for ( ; temp <16; temp++) i 
HoldNetworkNameCtemp] = ' *; 

> 
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Listing 8-2. (cont.) 


if (*argv[1] == •**) 

printf ("\nRequesting status for Local primary adapter."); 

else 

printf ("XnRequesting status for %s", argvH]); 
break; 

> 

return SUCCESS; 


> 

void LogoO 
{ 

printf ("\n NetBIOS Adapter Status Program"); 

printf ("\n © Copyright 1988 W. David SchwadererVn") ; 

> 

void ExplainO 

printf ("\nusage: status Node-ID\n"); 

printf("\n Node-ID: Wx.hh.hh.hh.hh.hh.hh for Permanent Node ID"); 
printf ("\n -or- 12345 !S#$*aBcDeF for Network Name"); 

printf ("\n -or- * for Local Primary Adapter Status"); 

> 

void ExitNowO 

printf ("\n\n\x07Program ending. . .\n") ; 
exit (1); 

> 


The Adapter Reset and Adapter Status Synergy 

Resetting PC Network LANA adapters with varying maximum session 
and pending command values determines the maximum message size 
packet the adapter can transmit. (Note this does not apply to other IBM 
LAN adapters and the maximum datagram size is always 512 bytes for PC 
Network LANA adapters.) 

It is possible to reveal the exact undocumented effect these com- 
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bined parameters have on the maximum packet size by issuing Adapter 
Reset commands while varying their values from 1 to 32 and by issuing 
intervening Adapter Status commands. The results differ for the two dif- 
ferent levels of NetBIOS available for PC Network LANA adapters and are 
displayed in Figures 8-1 and 8-2. 


,, /cmd rz — 



Fig. 8-1. Packet size (in bytes) as a function of /CMD and /SES for 
LANA protocol level 1.23. 
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Fig. 8-2. Packet size (in bytes) as a function of /CMD and /SES for 
LANA protocol level 1.33. 


The NetBIOS Cancel Sample Program 

The NetBIOS Cancel sample program in Listing 8-3 illustrates the proce- 
dure to cancel a pending Neb command. The program begins by invok- 
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ing Logo( ) to display a logo. It then invokes Requests tatus( ) which 
issues an Adapter Status command with a no-wait option for a network 
name consisting of 16 uppercase X’s. Since such a name is unlikely to 
exist, the NetbiosRequest( ) routine should return before the command 
completes. 


Listing 8-3. CANCEL.C 

#define LINT_ARGS 

#include <dos.h> 

^include <stdio.h> 

#include "netbiosZ.h" 

struct SREGS SegRegs; 

struct Neb StatusNcb, CanceLNcb; 

struct DLcStatus DLcData; 

#if defined(LINT_ARGS) 

extern int mainCint argc,char * *argv); 

extern void RequestStatus(void) ; 

extern void CancelRequestStatus(void) ; 

extern void AnaLyzeNcbStatus(void); 

extern void CLearNcbCstruct Neb *NcbPtr); 

extern void NetbiosRequest (struct Neb *NcbPointer) ; 

extern void Logo (void); 

/^endif 

int nfiain(argc, argv) 
int arge; 
char *argv[]; 

unsigned char temp; 

LogoO ; 

RequestStatusO ; 

CanceLRequestStatusO ; 

AnalyzeNcbStatusO ; 
putchar(*\n*); 


return 0; 



90 


Part II: Support Programming 


Listing 8-3. (cont.) 


void RequestStatusO 
int temp; 

char far ★StatusBufferPtr = (char far *) &DLcData; 
CLearNcbC&StatusNcb) ; 

StatusNcb.NcbBufferOffset = (char ★) FP_OFF(StatusBuf ferPtr) ; 

StatusNcb.NcbBuf ferSegment = (unsigned) FP_SEG(StatusBuf ferPtr) ; 

StatusNcb.NcbCommand = NETBIOS_ADAPTER_STATUS + NO_WAIT; 

StatusNcb.NcbLength *= si ?eof (DLcData) ; 

StatusNcb.NcbLanaNum = 0; 

for (temp = 0; temp < 16; temp++) '' 

StatusNcb.NcbCal INameCtemp] = *X'; 

NetbiosRequest (&StatusNcb) ; 

> 

void CancelRequestStatus () 

{ 

struct Neb far *NcbPtr = (struct Neb far *) SStatusNcb; 
ClearNcb(&CancelNcb) ; 

CanceLNcb.NcbBufferOffset = (char *) FP_OFF(NcbPtr) ; 

CanceLNcb.NcbBufferSegment = (unsigned) FP_SEG(NcbPtr) ; 

CanceLNcb.NcbCommand = NETBIOS_CANCEL_WAIT_ONLY; 

CanceLNcb.NcbLanaNum = 0; 

NetbiosRequest (SCanceL Neb) ; 

> 

void AnaLyzeNcbStatusO 

printf ("\nCancel NebRetCode ==> %02Xh", CancelNcb.NcbRetCode) ; 
printf ("\nStatus NebRetCode ==> %02Xh”, StatusNcb. NebRetCode) ; 

> 


void C learNcb(NcbPtr) 
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Listing 8-3. (cont.) 

struct Neb *NcbPtr; 

{ 

i nt i ; 
char ★CharPtr; 

CharPtr = (char *) NcbPtr; 

for ( i = 0; i < si zeof (ZeroNcb) ; i++ ) 

*CharPtr++ = 0x00; 

> 

void NetbiosRequest (NebPointer) 
struct Neb *NcbPointer; 

union REGS InRegs, OutRegs; /* defined in dos.h */ 
struct Neb far *NcbPtr = (struct Neb far *) NebPointer; 

segread(&SegRegs) ; 

SegRegs.es = FP_SE6(NcbPtr) ; 

InRegs.x.bx = FP_0FF(NcbPtr); 

int86x(NetbiosInt5C, SlnRegs, SOutRegs, SSegRegs); 

> 

void LogoO 

printf("\n NetBIOS Cancel Program”); 

printfC'Xn © Copyright 1988 W. David Schwaderer \n''); 

> 


The program invokes CancelRequestStatus( ) to cancel the presuma- 
bly pending Adapter Status command. The pending command uses an 
Neb named StatusNcb that has program scope, so CancelRequestStatus( ) 
can easily address it. Because the Cancel command has only a Wait form, 
its NetbiosRequest( ) returns synchronously — after the command has 
completed. Finally, the program invokes AnalyzeNcbStatus( ) to present 
the NebRetCode values of both the Adapter Status and Cancel com- 
mands. If the program has successfully completed, these return codes 
should be OBh and OOh, respectively. 

Normally, a program should never leave a command pending before 
exiting, though it is possible in this program for the Cancel command to 
fail under unusual circumstances. In this situation, the Adapter Status com- 
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mand completes when the adapter’s system time-out expires or when the 
target adapter responds successfully. If the latter occurs, NetBIOS then al- 
ters the memory where the Adapter Status buffer was located. In any 
event, NetBIOS alters the memory where the Neb was located. At worst, 
NetBIOS then detects a nonzero Post Routine field value and begins exe- 
cution at some (usually) disastrous point in memory. If you execute this 
program and the Cancel command is not successful, you may wish to reset 
your adapter to clear the pending Adapter Status command. 


The NetBIOS Unlink Sample Program 

The NetBIOS Unlink sample program in Listing 8-4 illustrates the Net- 
BIOS Unlink command that disconnects a client PC Network LANA 
adapter from an RPL server. The command is trapped by the adapter’s 
native ROM NetBIOS and is converted to a Hang Up command that uses 
another Neb. 

You will likely never need to use this command, but it is supported in 
many versions of NetBIOS for compatibility with IBM’s original Net- 
BIOS. In any event, its utility is increasingly limited with passing time. 
Note that a PC Network LANA’s NetBIOS virtually always returns a zero 
return code unless a very unusual condition occurs. Part I discusses this 
command in more detail. 


Listing 8-4. UNLINK.C 

#define LINT_ARGS 

^include <dos.h> 

^include <stdio.h> 

^include ”netbios2.h'' 

#if defined(LINT_ARGS) 

extern int main(int argc,char * *argv); 

extern void Logo(void); 

extern void UnlinkAdapterNow(void) ; 

extern void NetbiosRequest (struct Neb *NcbPointer) ; 

#endi f 

struct Neb UnlinkNcb; 

int mainCarge, argv) 
int arge; 
char *argv[]; 
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Listing 8-4. (cont.) 

LogoO ; 

UnLinkAdapterNowO ; 
return 0; 


void LogoO 

printf ("\n 
printf (''\n 

> 

void UnLinkAdapterNowO 

printf ("\n\nAttempting to Unlink NetBIOS adapter 0..."); 
UnLinkNcb.NcbCommand = NETBIOS_UNLINK_WAIT_ONLY; /* Unlink command code */ 
UnlinkNcb.NcbLanaNum = 0x00; /* unchecked, but should be zero */ 

NetbiosRequest C&UnlinkNcb) ; 
if ( lUnlinkNcb.NcbRetCode) -C 

printf ("\n\nAs hard-coded by NetBIOS, the return code was %x.\n", 

UnLinkNcb.NcbRetCode) ; 

> 

else { 

printf ("\n\n\x07The return code was %x ", UnLinkNcb.NcbRetCode); 

> 


void NetbiosRequest (NcbPointer) 
struct Neb *NcbPointer; 

{ 

union REGS InRegs, OutRegs; /* defined in dos.h */ 
struct SREGS SegRegs; /* defined in dos.h */ 

struct Neb far ^^fNcbPtr = (struct Neb far ★) NcbPointer; 

SegRegs.es = FP^SEGCNcbPtr) ; 

InRegs. x.bx = FP^OFFCNcbPtr); 

int86x(NetbiosInt5C, &InRegs, &OutRegs, &SegRegs); 

> 


NetBIOS Adapter Unlink Sample Program"); 
© Copyright 1988 W. David Schwaderer") ; 
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The NetBIOS Name Activity sample program, Listing 9-1, with routines 
NetbiosAddName( ) and FileNetbiosNameTable( ) illustrate how to add 
and delete NetBIOS names to and from local name tables. 


The NetBIOS Name Activity Sample Program 

The main( ) routine begins by invoking Logo( ) which displays a logo. It 
then resets the adapter insuring that the NetBIOS name table is empty 
and that there are no pending commands. It then calls the NetbiosAdd- 
Name( ) routine. 

When NetbiosAddName( ) returns, it resets the adapter to allow 
FillNetbiosNameTable to demonstrate NcbNum values beginning at 02h 
after each adapter reset. It then calls FillNetbiosNameTable( ). When 
FillNetbiosNameTable( ) returns, the program resets that adapter for the 
last time and exits. 


Listing 9-1. NAME.C 

/(define LINT_ARGS 

#incLude <dos.h> 

#incLude <stdio.h> 

^include ''netbios2.h" 

UM defined(LINT_ARGS) 

extern int mainCint argc,char * *argv); 

extern void AddNetbiosName(void) ; 

extern void DeleteNetbiosNameCunsigned char NetbiosNameChar) ; 
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Listing 9-1. (cont.) 

extern void Fi L INetbiosNameTabLe(void) ; 

extern void ResetAdapter (void) ; 

extern void Logo(void); 

extern void ClearNcbCstruct Neb *NcbPtr); 

extern void NetbiosRequest (struct Neb *NcbPointer) ; 

#endi f 

struct Neb NameNcb; /★ automatically set to zero in static storage */ 

int main(argc, argv) 
int arge; 
char *argv[]; 

{ 

LogoO ; 

ResetAdapterO ; 

AddNetbiosNameO ; 

ResetAdapterO ; 

Fi I INetbiosNameTableO ; 

ResetAdapterO ; 
putchar( * \n' ) ; 

return 0; 

> 

void AddNetbiosNameO 
USGC i = 0; 

printf ("\n\nNetBIOS Add Name Example...”); 

printf(”\n Adding the name 'A'+%02Xh+00h+. . .+00h. ”, i); 

ClearNcb(&NameNcb) ; 

NameNcb. NebCommand = NETBIOS_ADD_NAME; 

NameNcb. NebNameCO] = 'A'; 

NameNcb. NebNameCI ] = i; 

NameNcb. NebLanaNum = 0; 


NetbiosRequest (SNameNcb) ; 
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Listing 9-1. (cont.) 

printf("\n Its NcbNum value is %02Xh.", NameNcb.NcbNum) ; 
DeleteNetbiosNamed ) ; 


void DeleteNetbiosName(NetbiosNameChar) 

USGC NetbiosNameChar; 

< 

struct Neb DeleteNameNcb; 

printf ("\n\nNetBIOS Delete Name Example...”); 

printfC'Nn Deleting the name *A'+%02Xh+00h+. . .+00h. ” 

NetbiosNameChar) ; 

ClearNcb(&DeleteNameNcb) ; 


DeleteNameNcb. NebCommand = NETBIOS_DELETE_NAME; 
DeleteNameNcb. NebNameCO] = *A'; 

DeleteNameNcb. NcbNameU ] = NetbiosNameChar; 
DeleteNameNcb. NebLanaNum = 0; 

NetbiosRequest (&DeleteNameNcb) ; 


> 


printf (”\n The Delete Name command return code was %02Xh.”, 

DeleteNameNcb. NebRetCode) ; 


void Fi I INetbiosNameTableO 
USGC i = 1; 

printf (”\n\nNetBIOS Name Table exhaustion exercise...”); 
ClearNcbC&NameNcb) ; 

while ( INameNcb. NebRetCode) -C /* add names until there is an error */ 
printf (”\n Adding the Group Name ' A'+%02Xh+00h+. . .+00h now. ”, i); 
ClearNcbC&NameNcb) ; 

NameNcb. NebCommand = NETBIOS_ADD_GROUP_NAME; 

NameNcb. NebNameCO] = 'A*; 

NameNcb. NcbNamed ] = i++; 
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Listing 9-1. (cont.) 

NameNcb.NcbLanaNum = 0; 

Netbi osRequest (&NameNcb) ; 
if ( ! NameNcb.NcbRetCode) 

printfC'Its NcbNum value is %02Xh.'', NameNcb.NcbNum) ; 
else 

printf("\n The Add Group Name command failed..."); 

> 

printf("\n The failing Add Group Name command return code was %02Xh.", 

NameNcb.NcbRetCode) ; 

printf ("\n\nThe adapter's name table holds %u added names...", 

i-2); 

pri ntf ("\n\nExi ti ng the Name Table exercise."); 

> 

void ResetAdapter () 
struct Neb ResetNcb; 
printf ("\n\nResetting the adapter. "); 

ResetNcb. NebCommand = NETBI0S_RESET_WAIT_0NLY; /* reset command code */ 

ResetNcb. NebLanaNum = 0; /* adapter number */ 

ResetNcb. NcbLsn = 32; /* concurrent session count */ 

ResetNcb. NcbNum = 32; /★ concurrent command count */ 

Netbi osRequest (SResetNcb) ; 

printf ("The Reset command return code was %02Xh.", ResetNcb. NebRetCode) ; 

> 

void LogoO 
{ 

printf ("\n NetBIOS Name Activity Sample Program"); 

printf ("\n © Copyright 1988 W. David Schwaderer") ; 

> 


void ClearNcb(NcbPtr) 
struct Neb *NcbPtr; 
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Listing 9-1. (cont.) 


int i; 
char *CharPtr; 

CharPtr = (char *) NcbPtr; 

for ( i = 0; i < si zeof (ZeroNcb) ; i++ ) 

*CharPtr++ = 0x00; 

> 

voi d Netbi osRequest (NcbPoi nter) 
struct Neb *NcbPointer; 

union REGS InRegs, OutRegs; 
struct SREGS SegRegs; 

struct Neb far *NcbPtr = (struct Neb far *) NebPointer; 

segread(&SegRegs) ; 

SegRegs.es = FP_SEG(NcbPtr) ; 

InRegs. x.bx = FP_OFF(NcbPtr) ; 

int86x(NetbiosInt5C, &InRegs, &OutRegs, &SegRegs) ; 

> 


The AddNetbiosName Routine 

The AddNetbiosName routine adds a unique name to the NetBIOS name 
table using a wait option. When the command completes, the routine 
displays the name’s NebNum value which should be 02h because of the 
previous Adapter Reset command. (AddNetbiosName( ) assumes the Add 
Name command successfully completed.) Before exiting, AddNetbios- 
Name( ) invokes DeleteNetbiosName( ) to delete the name from the Net- 
BIOS name table. At this point, the next NebNum value should be 03h, 
but the adapter is reset by main( ) after AddNetbiosName returns. 


The FillNetbiosNameTable Routine 

FillNetbiosNameTable( ) is a brute force routine that determines how 
many names an adapter’s NetBIOS name table can hold. It continues to 
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add unlikely group names until an Add Group Name command returns a 
nonzero return code. 

When a command is successful, FillNetbiosNameTable( ) displays the 
associated NcbNum which should start at 02h because of the Adapter Re- 
set that main( ) issued immediately before calling FillNetbiosNameTable. 
Otherwise, the command fails and the routine displays the failing return 
code before exiting. Note that the return code should be OEh if the name 
table has been filled. 

Finally, note that this routine may take a long time to complete if the 
NetBIOS name table holds many names. 
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Datagram Support Programming 


This chapter presents a simple datagram application that determines the 
maximum size datagram an adapter can transmit. If the IBM LAN Support 
program controls the adapter, the value of the maximum datagram size is 
available at offset 48 (decimal) in returned adapter status information. 
However, other NetBIOS implementations do not provide this informa- 
tion with an Adapter Status command, so another method is required. 

The program in Listing 10-1 uses a brute force approach that begins 
by transmitting a one-byte datagram. If the datagram transmission is suc- 
cessful, the program increments the datagram size and transmits another 
datagram. This continues until an error occurs. 

Listing 10-1. MAXDG.C 

^define LINT_ARGS 

^include <dos.h> 

^include <stdio.h> 

#incLude "netbios2.h" 

struct SREGS SegRegs; 

struct Neb DatagramNcb; 

char BufferCI]; 

char ClientName[16] = "WDS-Datagram"; 

#if defined(LINT^ARGS) 

extern int mainCint argc,char * *argv); 

extern void Ini tDatagramNcb(void) ; 

extern void XmitDatagramCunsigned int Length); 


101 



102 


Part II: Support Programming 


Listing 10-1. (cont.) 

extern void CLearNcbCstruct Neb ★NcbPtr); 

extern void NetbiosRequest (struct Neb *NcbPointer) ; 

extern void Logo(void); 

#endi f 

int mainCarge, argv) 
int arge; 
char *argv[]; 

C 

USGC XmitError = FALSE; 

USGI LastGoodSize, SendSize = 1; 

LogoO ; 

printf ("\n") ; 

InitDatagramNcbO ; 

whi Le( IXmitError) { 

Xmi tDatagramCSendSi ze) ; 
if (DatagramNcb.NcbRetCode) { 

XmitError = TRUE; 

LastGoodSize = SendSize - 1; 

> else { 

SendSi ze++; 
putcharC ' . *) ; 

> 

> 

printf ("\n\nDatagram Send failed; return code == %02Xh", 

DatagramNcb.NcbRetCode) ; 

printf ("\n\nMaximum datagram length == %u bytes... \n", 

LastGoodSize) ; 


return 0; 

> 

void InitDatagramNcbO 
{ 

USGI temp; 


char far * BufferPtrFar = (char far *) Buffer; 
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Listing 10-1. (cont.) 


ClearNcbC&DatagramNcb) ; 

DatagramNcb.NcbCommand = NETBI0S_SEND_DATA6RAM; 

DatagramNcb.NcbBuf ferOffset = (char *) FP_OFF (Buf ferPt rFar) ; 
DatagramNcb.NcbBuf ferSegment = (USGI) FP_SEG(BufferPtrFar) ; 

DatagramNcb.NcbNum = 0x01; /* use Permanent Node Name NameNum */ 

for (temp = 0; temp < 16; temp++) 

DatagramNcb.NcbCaL LNameCtemp] = CLientNameLtemp] ; 

> 

void XmitDatagram(Length) 

USGI Length; 

DatagramNcb.NcbLength = Length; 

Netbi osRequest (&DatagramNcb) ; 

> 

void CLearNcb(NcbPtr) 
struct Neb *NcbPtr; 

i nt i ; 
char *CharPtr; 

CharPtr = (char *) NcbPtr; 

for ( i = 0; i < si zeof (ZeroNcb) ; i++ ) 

*CharPtr++ = 0x00; 

> 

void Netbi osRequest (NebPoi nter) 
struct Neb *NcbPointer; 

union REGS InRegs, OutRegs; /* defined in dos.h */ 
struct Neb far *NcbPtr = (struct Neb far *) NebPointer; 

segread(&SegRegs) ; 

SegRegs.es = FP_SEG(NcbPtr) ; 

InRegs.x.bx = FP_0FF(NcbPtr) ; 


int86x(NetbiosInt5C, &InRegs, &0utRegs, &SegRegs); 
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Listing 10-1. (cont.) 


void LogoO 

printf("\n NetBIOS Datagram Size Program"); 
printfC'Xn © Copyright 1988 W. David Schwaderer") ; 


The main( ) Function 

The main( ) function begins by calling Logo( ) to present a logo. It then 
calls InitDatagramNcb( ), which initializes a Send Datagram Neb with a 
wait option. After initializing the Neb, main( ) enters a while loop which 
terminates when the variable XmitError becomes TRUE. 

In this loop, main( ) calls XmitDatagram( ) and provides it with a 
datagram length. After XmitDatagram( ) returns, main( ) checks the re- 
turn code for success. If it is successful, main( ) increments the datagram 
size, displays a period (.) to provide user feedback, and begins another 
execution of the loop. 

Alternatively, the command fails and the loop terminates because the 
variable XmitError is set to TRUE. If the command fails because the size 
is too large, the return code is 01 h (Illegal Buffer Length). Before exiting, 
main( ) displays the failing command’s return code and the size of the last 
successfully transmitted datagram. 

Note the program repeatedly uses the same Neb but never reinitial- 
izes it. This is generally not advisable, but is acceptable in this instance 
because the command uses a wait option and the values of the Neb fields 
initialized by InitDatagramNcb( ) do not vary. Most importantly, the Neb 
is located in static storage and is not an automatic variable. 


IiiitDatagra]nNcb( ) and XmitDatagi*am( ) 

InitDatagramNcb( ) initializes all fields required for a Send Datagram with 
the exception of the NcbLength field. XmitDatagram( ) initializes this 
field immediately before issuing the command. Since the command 
specifies the wait option, control returns to XmitDatagram( ) synchro- 
nously at the command’s completion and XmitDatagram( ) immediately 
returns to main( ). 
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Intermediate Datagram Applications 


This chapter presents two datagram applications that respectively act as 
server and client applications. The server datagram application periodi- 
cally broadcasts current date and time information to potential clients. 

Using datagrams allows an unlimited number of clients to receive 
date and time information from an unlimited number of servers. Having 
multiple clients simultaneously use the same datagram economizes the 
LAN’s transmission capability, and having more than one server provides 
a measure of insurance that client PCs can always receive date and time 
information. Neither of these advantages are easily achieved using ses- 
sion communication. 

Client machines can subsequently use the date and time information 
to set their current date and time during AUTOEXEC.BAT execution. This 
procedure is analogous to procedures used to initialize a machine’s date 
and time from a battery-backed clock-calendar board. 


A Date and Time Server Application 

The server application uses its permanent node name to beacon 
datagrams containing the current date and time. The program in Listing 
11-1 terminates when a Ctrl-Break is struck at the keyboard. Note that the 
implementation of this application allows multiple date and time servers 
to exist simultaneously on a given network. 

Listing 11-1. DATETIME.C 

#define LINT_ARGS 
//include <dos.h> 
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Listing 11-1. (cont.) 

#incLude <stdio.h> 

#incLude "netbios2.h" 

struct SREGS SegRegs; 

struct Neb DateTimeNcb; 

USGC TimeNameNum; 

struct DateTimeStruct DateTimeInfo; 

char ClientNaine[16] = "WDS-DateTime"; 

#if defined(LINT_ARGS) 

extern int mainCint argc,char * *argv); 

extern void FetchDateAndTime(void) ; 

extern void Xmi tDateTime(void) ; 

extern void CLearNcbCstruct Neb *NcbPtr); 

extern void NetbiosRequest (struct Neb *NcbPoi nter) ; 

extern void Logo(void); 

#endi f 

int mainCarge, argv) 
int arge; 
char *argv[]; 

unsigned char temp; 

LogoO; 

printf ("\n") ; 

whiLe(TRUE) { 

FetchDateAndTimeO ; 

XmitDateTimeO; 
putcharC ' . ' ) ; 

> 

putcharC ' \n' ) ; 
return 0; 

> 

#define D0S_INT 0x21 

#define DOS FETCH DATE 0x2A 
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Listing 11-1. (cont.) 

#define DOS^FETCH_TIME 0x2C 

void FetchDateAndTimeO 

union REGS InRegs, OutRegs; 

InRegs.h.ah = DOS_FETCH_DATE; 

int86(D0S_INT, &InRegs, &0utRegs); 

DateTimeInfo.DateCX = OutRegs. x.cx; 

DateTimeInfo.DateDX = OutRegs. x.dx; 

InRegs.h.ah = DOS_FETCH_TIME; 

int86(D0S_INT, SlnRegs, &OutRegs); 

DateTimeInfo.TimeCX = OutRegs. x.cx; 

DateTimeInfo.TimeDX = OutRegs. x.dx; 

> 

void Xtni tDateTimeO 
USGI temp; 

char far * BufferPtrFar = (char far *) &DateTimeInfo; 
CLearNcbC&DateTimeNcb) ; 

DateTimeNcb.NcbCommand = NETBIOS_SEND_DATAGRAM; 

DateTimeNcb.NcbBufferOffset = (char ★) FP_OFF(BufferPtrFar) ; 
DateTimeNcb.NcbBufferSegment = (USGI) FP_SEG(BufferPtrFar) ; 

DateTimeNcb.NcbLength = sizeof (DateTimeInfo) ; 

DateTimeNcb.NcbNum = 0x01; /* use Permanent Node Name NameNum */ 

for (temp = 0; temp < 16; temp++) 

DateTimeNcb.NcbCallNameCtemp] = ClientNameCtemp] ; 

Netbi osRequest (&DateT i meNcb) ; 

> 


void CLearNcb(NcbPtr) 
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Listing 11-1. (cont.) 


struct Neb *NcbPtr; 

{ 

i nt i ; 
char *CharPtr; 

CharPtr = (char *) NcbPtr; 

for ( 1 = 0; i < si zeof (ZeroNcb) ; i++ ) 

*CharPtr++ = 0x00; 

> 

void NetbiosRequest (NebPointer) 
struct Neb *NcbPointer; 

union REGS InRegs, OutRegs; /* defined in dos.h */ 
struct Neb far *NcbPtr = (struct Neb far *) NebPointer; 

segread(&SegRegs) ; 

SegRegs.es = FP_SEG(NcbPtr) ; 

InRegs. x.bx = FP_OFF(NcbPtr) ; 

int86x(NetbiosInt5C, &InRegs, SOutRegs, &SegRegs); 

> 

void LogoO 
{ 

printf("\n NetBIOS Date/Time Server Program”); 
printf(”\n © Copyright 1988 W. David Schwaderer”) ; 

> 


The main( ) Function 

The main( ) function begins by calling Logo( ) to present a logo. It then 
enters an infinite loop which invokes FetchDateAndTime( ) and 
XmitDateAndTime( ), and displays a period (.) to provide user execution 
feedback. The loop ends when a Ctrl-Break is struck at the keyboard. 

FetchDateAndTime( ) 

FetchDateAndTime( ) issues two PC-DOS calls that fetch the current date 
and time, respectively. After each respective PC-DOS call, it places the 
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supplied information in the appropriate DateTimeInfo structure ele- 
ment. Appendix A presents a netbios2.h listing containing a complete 
structure declaration for DateTimeStruct. 


XmitDateAndTime( ) 

XmitDateAndTime( ) initializes all required DateTimeNcb structure ele- 
ments with appropriate values and invokes NetbiosRequest( ) to transmit 
the data. Note that it uses the permanent node NcbNum value 01 h for the 
NcbNum value. This allows the program to transmit datagrams without 
adding or deleting a name to or from the NetBIOS name table. 

The client name has a value of “WDS-DateTime” followed by four 
bytes of binary zeros. These zeros result from the ClientName character 
array definition’s defaulting the last four characters in its specification. 
The C default is binary zero. 


A Date and Time Client Application 

The date and time client application in Listing 11-2 is more complicated 
than its server counterpart because it adds and deletes a name from the 
NetBIOS name table. Moreover, it cannot assume a server is providing 
date and time information. Thus, the client application issues a no- wait 
option Receive Datagram command allowing it to cancel the Receive 
Datagram if a prudent period elapses and no information is received. 
Note some program functions are not described because they are similar 
to previously described functions. 

Listing 11-2. The SET_D_T.C 

i/define LINT_ARGS 

//include <dos.h> 

#include <time.h> 

#incLude <stdio.h> 

//include "netbiosZ.h” 

struct SREGS SegRegs; 

struct Neb DateTimeNcb; 

USGC TimeNameNum; 
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Listing 11-2. (cont.) 
struct DateTimeStruct DateTimeInfo; 


char ClientName[16] = "WDS-DateTime"; 


#if defined(LINT_ARGS) 


extern 
extern 
extern 
extern 
extern 
extern 
extern 
extern 
extern 
extern 
extern 
extern 
extern 
extern 
#endi f 


int mainCint argc,char * *argv); 

int AddCLientName(void) ; 

void IssueDateTimeRequest (void) ; 

void Delay(void); 

void DelayTickCvoid) ; 

void SetDateTimeAttempt (void) ; 

void SetDateAndTimeNow(void) ; 

void Cancel DateTimeRequest (void) ; 

void DeleteCLientName(void) ; 

void Di spLayDateAndTime(void) ; 

void FetchDateAndTime(void) ; 

void CLearNcb(struct Neb *NcbPtr); 

void NetbiosRequest (struct Neb *NcbPointer) ; 

void Logo (void); 


#define TICK_RATE 18.2 
#define SECONDS 5 

^define DELAY_TICK_COUNT (TICK_RATE * SECONDS) 


int main(argc, argv) 
int arge; 
char *argv[]; 

{ 

unsigned char temp; 

LogoO ; 

if (AddCLientNameO) -C 

IssueDateT i meRequest () ; 

Delay () ; 

SetDateT i meAttempt 0 ; 

DeleteClientNameO ; 

> else 

printf ("\n\nProgram ending because of add-name failure.”); 
Di splayDateAndTimeO ; 


putchar( ' \n' ) 
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Listing 11-2. (cont.) 


return 0; 

> 

int AddClientNameO 
{ 

struct Neb AddNameNcb; 

USGI temp = 0; 

CLearNcbC&AddNameNcb) ; 

AddNameNcb. NebCommand = NETBIOS_ADD_GROUP_NAME; 

AddNameNcb. NebLanaNum = 0; 

for (temp = 0; temp < 16; temp++) 

AddNameNcb. NebNameCtemp] = ClientNameCtemp] ; 

printf (''\n\nAdding the client name. . .please wait..."); 

Netbi osRequest C&AddNameNcb) ; 

if (! AddNameNcb. NebRetCode) -C 
printf ("\n The add-name was successful..."); 
printf("\n The client's NebNum value is %02Xh.", 

AddNameNcb. NebNum) ; 

TimeNameNum = AddNameNcb. NebNum; 
return SUCCESS; 

> else { 

return FAILURE; 

printf ("\n The add-name was not successful..."); 

> 

> 

void IssueDateTimeRequest () 

char far * BufferPtrFar = (char far *) SDateTimelnfo; 
ClearNcb(&DateTimeNcb) ; 

DateTimeNcb. NebCommand = NETBIOS_RECEIVE_DATAGRAM + N0_WAIT; 

DateTimeNcb.NcbBufferOff set = (char *) FP_0FF (BufferPtrFar) ; 
DateTimeNcb. NebBufferSegment = (USGI) FP_SEG(Buf ferPtrFar) ; 
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Listing 11-2. (cont.) 


DateTimeNcb.NcbLength = si zeof (DateTimelnfo) ; 

DateTimeNcb.NcbNum = TimeNameNum; 

NetbiosRequest (SDateTimeNcb) ; 

> 

void DelayO 

USGC Quit = FALSE; 

USGI DeLayedTicks = 0; 

printf ("\n\nAttempting to fetch the date and time from the network...”); 
printf ("please wait...”); 

while (!Quit) { 

if (DateTimeNcb.NcbCmdCplt != OxFF) -C 
return; 

> else { 

DelayTickC); 

if (DelayedTicks++ > DELAY_TICK_COUNT) 
return; 

> 

> 

> 

#define D0S_INT 0x21 

#define DOS_FETCH_TIME 0x2C 

void DelayTickC) 

{ 

union REGS InRegs, OutRegs; 

USGC EntryHundredths; 

InRegs. h. ah = DOS_FETCH_TIME; 

int86(D0S_INT, SlnRegs, &0utRegs); 

EntryHundredths = OutRegs. h.dl; 

while(TRUE) { 

int86(DOS_INT, SlnRegs, &OutRegs); 
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Listing 11-2. (cont.) 

if (EntryHundredths != OutRegs.h.dL) 
break; 

> 

return; 

> 

void SetDateTimeAttempt 0 
{ 

if ((DateTimeNcb.NcbCmdCplt != OxFF) && 

(DateTimeNcb.NcbCmdCpLt == 0x00) ) { 

SetDateAndTimeNowO ; 

> else { 

printf C'XnXnNo network response..."); 

printfC'Xn Canceling the pending receive datagram..."); 

CancelDateTimeRequest () ; 

> 


#define D0S_SET_DATE 0x2B 
#define DOS_SET_TIME 0x20 

void SetDateAndTimeNowO, 

union REGS InRegs, OutRegs; 

printf ("XnXnSetting date and time from the network..."); 

InRegs. h. ah = D0S_SET_DATE; 

InRegs. x.cx = DateTimeInfo.DateCX; 

InRegs. x.dx = DateTimeInfo.DateDX; 

int86(D0S_INT, &InRegs, &0utRegs); 

InRegs. h. ah = DOS_SET_TIME; 

InRegs. x.cx = DateTimeInfo.TimeCX; 

InRegs. x.dx = DateTimeInfo.TimeDX; 

int86(D0S_INT, SlnRegs, SOutRegs); 

> 

void CancelDateTimeRequest O 


struct Neb CancelNcb; 
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Listing 11-2. (cont.) 


struct Neb far *NcbPtr = (struct Neb far ★) SDateTimeNcb; 
ClearNcbC&CancelNcb); 

CancelNcb.NcbBufferOffset = (char *) FP_OFF(NcbPtr) ; 
CancelNcb.NcbBufferSegment = (unsigned) FP_SEG(NcbPtr) ; 

CancelNcb.NcbCommand = NETBIOS^CANCEL^WAIT_ONLY; 

CancelNcb.NcbLanaNum = 0; 

NetbiosRequest (SCancelNcb) ; 

if ( ! CancelNcb.NcbRetCode) { 
printfC'Xn The cancel was successful...'*); 

> else { 

printf("\n The cancel was not successful..."); 

> 

> 

void DeleteClientNameO 

struct Neb DeleteNameNcb; 

USGI temp; 

printf ("\n\nDeleting client name..."); 
ClearNcb(&DeleteNameNcb) ; 

DeleteNameNcb. NebCommand = NETBIOS_DELETE_NAME; 
DeleteNameNcb. NebLanaNum = 0; 

for (temp = 0; temp < 16; temp++) 

DeleteNameNcb. NebNameCtemp] = ClientNameCtemp] ; 

NetbiosRequest (SDeleteNameNcb) ; 

if (! DeleteNameNcb. NebRetCode) 

printf ("\n The delete-name was successful..."); 
else { 

printf ("\n The delete-name was not successful..."); 
printf("\n The return code was %02Xh.", 

DeleteNameNcb. NebRetCode); 


> 
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Listing 11-2. (cont.) 


> 

void Di spLayDateAndTimeO 
FetchDateAndTimeO ; 

printf ("\n\nThe current date is %02u-%02u-%04u. . 

(US6C) (DateTimeInfo.DateDX » 8), 
(US6C) (DateTimeInfo.DateDX), 

(USGI) (DateTimeInfo.DateDX) ); 

printf ("\n\nThe current time is %02u:%02u:%02u. . 

(USGC) (DateTimeInfo.TimeCX » 8), 
(USGC) (DateTimeInfo.TimeCX), 

(USGC) (DateTimeInfo.TimeDX » 8) ); 

> 

#define DOS_FETCH_DATE 0x2A 
#define DOS_FETCH_TIME 0x2C 

void FetchDateAndTimeO 

union REGS InRegs, OutRegs; 

InRegs.h.ah = DOS^FETCH^DATE; 

int86(D0S_INT, SlnRegs, SOutRegs); 

DateTimeInfo.DateDX = OutRegs. x.cx; 

DateTimeInfo.DateDX = OutRegs. x.dx; 

InRegs.h.ah = DOS_FETCH_TIME; 

int86(D0S_INT, SlnRegs, SOutRegs); 

DateTimeInfo.TimeCX = OutRegs. x.cx; 

DateTimeInfo.TimeDX = OutRegs. x.dx; 

> 

void CLearNcb(NcbPtr) 
struct Neb *NcbPtr; 

i nt i ; 
char *CharPtr; 
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Listing 11-2. (cont.) 


CharPtr = (char *) NcbPtr; 

for ( i = 0; 1 < si zeof (ZeroNcb) ; i++ ) 

*CharPtr++ = 0x00; 

> 

void NetbiosRequest (NcbPointer) 
struct Neb *NcbPointer; 

union REGS InRegs, OutRegs; /* defined in dos.h */ 
struct Neb far *NcbPtr = (struct Neb far *) NcbPointer; 

segread(&SegRegs) ; 

SegRegs.es = FP_SEG(NcbPtr) ; 

InRegs.x.bx = FP_0FF(NcbPtr) ; 

int86x(NetbiosInt5C, SlnRegs, &OutRegs, &SegRegs); 

> 

void LogoO 

printf("\n NetBIOS Date/Time Client Program"); 
printf("\n © Copyright 1988 W. David Schwaderer") ; 


The main( ) Function 

The main( ) function begins by calling Logo( ) to present a logo. It then 
calls AddClientName( ) which attempts to add the client name as a group 
name. If the Add Group Name is successful then the NebNum value of 
the client name is saved in TimeNameNum, and AddClientName( ) re- 
turns to main( ) with a successful return code indication. Then, main( ) 
calls IssueDateTimeRequest( ) to issue the Receive Datagram request 
which uses the TimeNameNum value. 

After the Receive Datagram command is issued, main( ) calls Delay( ) 
to pause for an appropriate amount of time before calling SetDate- 
TimeAttempt( ) which tries to set the date and time. The program ends 
after displaying the machine’s current date and time, which may not be 
accurate if date and time information was not received. 
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Delay( ) 

Delay( ) displays a message that informs the user it is attempting to fetch 
the date and time from the network. It then enters a while loop that ter- 
minates when the variable Quit becomes TRUE. 

In this loop, Delay( ) repeatedly checks the NcbCmdCplt field to see 
if it has changed from a command-pending state. If it has, the variable 
Quit becomes TRUE and Delay( ) returns to main( ). Otherwise, Delay( ) 
calls DelayTick( ) which waits a machine tick (18.2 ticks per second) be- 
fore returning to Delay( ). DelayTick( ) senses a tick has occurred by re- 
peatedly fetching the current time from PC-DOS and watching for a 
change in the DL register. 

Delay( ) keeps track of how many ticks have occurred while the 
NcbCmdCplt remains in a command-pending state. After a number of 
ticks greater than DELAY_TICK_COUNT have occurred, Delay( ) re- 
turns to IssueDateTimeRequest( ) even though the Receive Datagram 
may still be pending. 


SetDateTimeAttempt( ) 

SetDateTimeAttempt( ) inspects the NcbCmdCplt field for a command- 
pending status. If the command is still pending, SetDateTimeAttempt( ) 
invokes CancelDateTimeRequest( ) to cancel the Receive Datagram com- 
mand and returns to main( ). Otherwise, SetDateTimeAttempt( ) calls 
SetDateAndTimeNow( ) which uses the received information to set the 
date and time with respective PC-DOS calls. 


DisplayDateAndTime( ) 

DisplayDateAndTime( ) invokes FetchDateAndTime( ) which fetches the 
current date and time with respective PC-DOS calls. FetchDateAnd- 
Time( ) places this current date and time information in appropriate 
DateTimeInfo structure elements before returning to DisplayDateAnd- 
Time( ). Subsequently, DisplayDateAndTime( ) displays this information 
before returning to main( ). 
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Real-Ume LAN Conferencing 
Application 


This chapter presents a datagram application providing a real-time LAN- 
conferencing capability. The program in Listing 12-1 allows several users 
to communicate with one another within a given conference, with each 
user seeing what the other users have entered from their keyboards. Mul- 
tiple conferences can also simultaneously exist, but input from one is not 
received by any other conference. 

Listing 12-1. CB.C 


#def ine 

LINT_ARGS 


#incLude 

<dos.h> 


^include 

<conio.h> 


^include 

<stdio.h> 


//include 

''netbios2.h" 


//define 

BIOS_VIDEO_REQUEST 

0x10 

#def ine 

CB^NAME^TERMINATOR 

0x80 

#def ine 

C0LUMN_1 

00 

//define 

COLUMN_80 

79 

#def ine 

ENTIRE_SCREEN 

00 

//define 

ESC 

0x1 B 

//define 

FETCH_CURSOR_POSITION 

0x03 

//define 

GROUP^NAME 

2 

//define 

MAX^KEYBOARD_MSG 

60 

//define 

MAX_NCBS 

5 

#def ine 

NAME_SIZE 

16 

#def ine 

NORMAL_ATTRIBUTE 

07 

//define 

0NE_LINE 

01 

#def ine 

PAGE_ZER0 

00 

#def ine 

RETURN 

OxOD 


lt9 
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Listing 12-1. (cont.) 


#def ine 

R0W_1 

00 

#def ine 

R0W_2 

01 

#def ine 

ROW_24 

23 

#def ine 

ROW_25 

24 

#def ine 

SCROLL_UP 

06 

#def ine 

SET_CURSOR_POSITION 

0x02 

#def ine 

UNIQUE NAME 

1 


#if defined(LINT_ARGS) 

extern int mainCint argc.char * *argv); 

extern void Participate(void) ; 

extern void IssueRecei veDatagramRequests(void) ; 

extern void ServiceDatagramNcbsCvoid) ; 

extern void ProcessRecei vedDatagramCunsigned int Index); 

extern void CancelRecei veDatagrams(void) ; 

extern void InitializeKeyboardInputAreaCvoid); 

extern void SetupInputLine(void) ; 

extern void Servi ceKeyboard(void) ; 

extern void AppLyKeystrokeCunsigned char Keystroke); 

extern void SendKeyboardMsgCchar *Message); 

extern void Emi tUserStatusMsgCchar *AppendMsg); 

extern int AddConferenceName(void); 

extern void DeLeteConferenceName(void) ; 

extern unsigned char AddUserName(void) ; 

extern void DeLeteUserName(void) ; 

extern void ClearNcbCstruct Neb *NcbPtr); 

extern unsigned char NetbiosAddNameCchar *Name,int NameType); 

extern void NetbiosDeleteNameCchar *Name); 

extern void NetbiosSendDatagramCstruct Neb *NcbPtr, 

struct DgStruct *Buf ferPt rNear , 
unsigned int BufferSize); 

extern void NetbiosRecei veDatagramCstruct Neb *NcbPtr, 

struct DgStruct *Buf ferPt rNear , 
unsigned int BufferSize); 

extern void NetbiosCancelNcbCstruct Neb *NcbPtrNear) ; 
extern void NetbiosRequest (struct Neb *NcbPtrNear) ; 
extern void Logo(void); 

extern int EditArgsCint argc,char * *argv); 
extern void Explain(void) ; 
extern void Exi tNow(void); 
extern void Cls(void); 

extern void ScroL LScreenCunsigned int BeginRow, 

unsigned int EndRow, 
unsigned int RowCount); 



Chapter 12: LAN Conferencing 


121 


Listing 12-1. (cont.) 


extern 

extern 

extern 

#endi f 


void FetchCursorPosi tion(void); 

void SetP rev iousCursorPosit ion (void) ; 

void SetCursorPosi tionCunsigned int Row, 

unsigned int Column); 


/*■ 


struct Neb InDgNcbCMAX^NCBS] , OutDatagramNcb; 

struct DgStruct -C char OriginName[NAME_SIZE] ; 

char TextCMAX_KEYBOARD_MSG]; 

>; 

struct DgStruct OutDatagram, InDgCMAX^NCBSl ; 

/^define DATAGRAM_MSG__SIZE si zeof (OutDatagram) 

char *ConferenceNamePtr, *UserNamePtr; 

USGC ConferenceNameNum, UserNameNum; 

USGI CurrentRow, CurrentColumn; 

/* 


*/ 


*/ 


int main(argc,argv) 
int arge; 
char *argvC]; 

LogoO ; 

if ( ! EditArgs(argc, argv)) 

Exi tNowO ; 

ConferenceNamePtr = argvEH; 

UserNamePtr = argvCZ]; 

if (AddConferenceNameO) -C 
if (AddUserNameO) { 

Parti cipateO ; 

ClsO; 

printf ("\n\nOnline program ending at user request .. .\n") ; 
CancelRecei veDatagramsO ; 

DeleteUserNameO ; 

> 

DeleteConferenceNameO ; 

> 
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Listing 12-1. (cont.) 


putchar('\n*); 
return 0; 

> 

/* */ 

USGI Participating = TRUE; 

char EnterAppendC] = " has joined the conference..."; 


char DepartAppendC] = " has left the conference..."; 
void Parti cipateO 

printf ("\n\n\n* — Online as user "); 
printf ("\"%s\" in conference \"%s\"...", 

UserNamePtr, ConferenceNamePtr) ; 

IssueRecei veOatagramRequestsO ; 

Emi tUserStatusMsg (EnterAppend) ; 

SetupInputLineO ; 

whi le(Participating) { 

Servi ceDatagramNcbsO ; 

Servi ceKeyboardO; 

> 

Emi tUserStatusMsg(DepartAppend) ; 

while (OutDatagramNcb.NcbCmdCplt == COMMAND^PENDING) 

; /* spin until complete */ 

> 

/*- Datagram Processing */ 

void IssueRecei veDatagramRequestsO 
USGI i; 

for (i = 0; i < MAX_NCBS; i++) 

NetbiosRecei veDatagramC&InDgNcbli ] , 

SlnDgCi ] , 
sizeof (InDgCi ])) ; 

> 
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Listing 12-1. (cent.) 

#define TARGET_NCB ( (Starti ngNcb + index) % MAX_NCBS) 
void Servi ceDatagramNcbs () 

static USGI StartingNcb = 0; /* must be static */ 

USGI index = 0; 

while <InDgNcbCTARGET_NCB].NcbCmdCpLt != COMMAND^PENDING) { 
ProcessRecei vedDatagram(TARGET_NCB) ; 

NetbiosRecei veDatagram(&InDgNcb[TARGET_NCB] , 
&InDg[TARGET_NCB], 
sizeof(InDg[TARGET_NCB3)); 

index++; 

> 

StartingNcb = TARGET_NCB; 

> 

void ProcessRecei vedDatag ram (Index) 

USGI Index; 

USGI i; 

if ( ! InDgNcbCIndex] .NebRetCode) -C 

FetchCursorPosi tionO ; 

ScroLlScreen(R0W_2, ROW_24, 1); 

SetCursorPosi tion(R0W_24, 0); 

printf("%s => %s", InDgCindex] .OriginName, 
InDgCindexl.Text); 

SetPreviousCursorPosi tionO ; 

> 

> 

void CancelRecei veDatagramsO 
USGI i; 

for (i = 0; i < MAX^NCBS; i++) i 

if (InDgNcbCil.NcbCmdCplt == COMMAND_PENDING) 


NetbiosCancelNcbC&InDgNcbCi ]) ; 
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> 


> 


Listing 12-1. (cont.) 


/★ Keyboard Handling */ 

char *KeyboardInputPtr , Keyboardinput [MAX_KEYBOARD_MSG] ; 

USGI KeyboardInputLength; 

void Initiali zeKeyboardInputAreaO 
{ 

i nt i ; 

for (i =1; i < MAX^KEYBOARD_MSG; i++) 

Keyboardinput [i ] = '\x00'; 

KeyboardInputPtr = Keyboardinput; 

KeyboardInputLength = 0; 

> 

void SetupInputLineO 
i nt i ; 

Set CursorPosi t i on (ROW_25 , COLUMNJ ) ; 

for (i =1; i <79; i++) 
putcharC '); 

Set CursorPos i t i on (ROW , COLUMNJ ) ; 

printf(''%s => '',UserNamePtr) ; 

Ini tia Li ZeKeyboardInputAreaO ; 

> 

void Servi ceKeyboardO 


USGC Keystroke; 
if (kbhitO) { 

switch (Keystroke = (USGC) getchO) -C 

case 0x00 : /* function key */ 

Keystroke = (USGC) getchO; 
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Listing 12-1. (cont.) 

break; 
case 0x08 : 

if (KeyboardInputLength > 0) { 
printf (''\x08 \x08"); 

— KeyboardInputLength; 

*( — KeyboardInputPtr) = '\x00'; 

> 

break; 


case ESC: /* quit indicator */ 

Participating = FALSE; 
break; 

case RETURN: /* send indicator */ 

SendKeyboa rdMsg ( Key boa rd Input ) ; 
break; 


default : 

ApplyKeystroke(Keystroke) ; 
break; 

> 

> 

> 

void AppLyKeystroke(Keystroke) 

US6C Keystroke; 

if ((KeyboardInputLength+1) >= MAX_KEYB0ARD_MS6) i 
putchar(’\x07*); 
return; 

> 

if ((Keystroke >= ' ') && (Keystroke < 128)) { 
KeyboardInputLength++; 

*(KeyboardInputPtr++) = (char) Keystroke; 

putchar(Keystroke) ; 

return; 

> 

> 

void SendKeyboardMsg (Message) 
char ^Message; 


USGI Index; 
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Listing 12-1. (cont.) 


if (KeyboardInputLength == 0) 
return; 

for (Index = 0; Index < NAME_SIZE; Index++) 
OutDatagram.OriginNameCIndex] = '\x00'; 

strncpyCOutDatagram.OriginName, UserNamePtr, NAME_SIZE); 

for (Index = 0; Index < MAX_KEYBOARD_MSG; Index++) 
OutDatagram. Text [Index] = '\x00*; 

strncpy(OutDatagram.Text , Message, MAX__KEYBOARD_MSG) ; 

NetbiosSendDatagranfi(&OutDatagramNcb, 

SOutDatagram, 

DATAGRAM_MSG_SIZE); 


SetupInputLineO ; 


/* 5 ^gi^ On/Off */ 

char MONITORS = "MONITOR ! \x07"; 

voi d Emi tUserStatusMsg (AppendMsg) 
char *AppendMsg; 

St rncpy (OutDatagram. OriginName, 

MONITOR, 

strLen(MONITOR)+1); 

St rncpy (OutDatagram. Text, 

UserNamePtr, 

St r ten (UserNamePtr) +1 ) ; 

strncat (OutDatagram. Text , AppendMsg) ; 

NetbiosSendDatagram(&OutDatagramNcb, 

SOutDatagram, 

DATAGRAM_MSG_SIZE); 

> 

/* Addi tion/Deletion */ 

int AddConferenceNameO 
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Listing 12-1. (cont.) 


USGC Temp; 

printf ("\n\n\nChecking the Conference Name 

Conf erenceNamePtr) ; 

Temp = NetbiosAddName (Conf erenceNamePtr, GROUP^NAME); 

if (Temp == ILLEGAL_NAME_NUM) 
return FAILURE; 
else i 

ConferenceNameNum = Temp; 
return SUCCESS; 

> 

> 

void DeLeteConferenceNameO 

printf (''\n\nDeleting the conference name..."); 

Net biosDeleteName (Conf erenceNamePtr) ; 

> 


USGC AddUserNameO 
USGC Temp; 

printf ("\n\n\nChecking the User Name \"%s\"...", 

UserNamePtr) ; 

Temp = NetbiosAddName(UserNamePtr, UNIQUE_NAME) ; 

if (Temp == ILLEGAL_NAME_NUM) 
return FAILURE; 
else -C 

UserNameNum = Temp; 
return SUCCESS; 

> 

> 


void DeleteUserNameO 

printf ("\n\nDeLeting your user name..."); 
NetbiosDe let eName (UserNamePtr) ; 

> 


/*- 


*/ 


Netbios Requests 
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Listing 12-1. (cont.) 

struct SREGS SegRegs; /* defined in dos.h */ 

void CLearNcb(NcbPtr) 
struct Neb *NcbPtr; 

int i ; 

char ★CharPtr = (char ★) NcbPtr; 

for ( i =0; i < sizeof (ZeroNcb); i++ ) 

*CharPtr++ = '\x00'; 

> 

USGC NetbiosAddNameCName, NameType) 
char *Name; 
int NameType; 

{ 

struct Neb AddNameNcb; 

NetbiosDeLeteName(Name) ; 

C LearNcbC&AddNameNcb) ; 

if (NameType == UNIQUE^NAME) 

AddNameNcb. NebCommand = NETBIOS_ADD_NAME; 

else 

AddNameNcb. NebCommand = NETBIOS_ADD_GROUP_NAME; 

strnepy (AddNameNcb. NcbName, Name, str Len(Name) ) ; 
AddNameNcb. NebNamedS] = CB^NAME_TERMINATOR; 

Netbi osRequest (SAddNameNcb) ; 

if (! AddNameNcb. NebRetCode) 
return AddNameNcb. NebNum; 
else -C 

printf (’'\n\n0x%02X error with add name...", 
AddNameNcb. NebRetCode) ; 

return ILLEGAL^NAME_NUM; 

> 

> 

void NetbiosDeLeteName(Name) 
char *Name; 

T 

struct Neb DeLeteNameNcb; 
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Listing 12-1. (cont.) 


CLearNcbC&OeleteNameNcb) ; 

DeLeteNameNcb.NcbCommand = NETBIOS_DELETE_NAME; 

strncpy (DeLeteNameNcb.NcbName, Name, strlen(Name)) ; 
DeleteNameNcb.NcbNameC15] = CB_NAME_TERMINATOR; 

NetbiosRequest (SDeleteNameNcb) ; 

> 

void NetbiosSendDatagramCNcbPtr, BufferPtrNear, BufferSize) 
struct Neb *NcbPtr; 
struct DgStruct *Buf ferPtrNear; 

US6I BufferSize; 

< 

struct DgStruct far *Buf ferPtrFar; 

while (NcbPtr->NcbCmdCplt == COMMAND_PENDING) 

; /* spin here for completion! */ 

ClearNcb(NcbPtr) ; 

NcbPtr->NcbCommand = NETBIOS_SEND_DATAGRAM + N0_WAIT; 

BufferPtrFar = (struct DgStruct far *) BufferPtrNear; 

NcbPtr->NcbBufferOf fset = (char *) FP_OFF(Buf ferPtrFar) ; 
NcbPtr->NcbBufferSegment = (US6I) FP_SEG(Buf ferPtrFar) ; 

NcbPtr->NcbLength = DATAGRAM_MSG_SIZE; 

NcbPtr->NcbNum = UserNameNum; 

strnepy (NcbPtr->NcbCa I IName, ConferenceNamePtr, NAME_SIZE); 
NcbPtr->NcbCallName[15] = CB_NAME_TERMINATOR; 

NetbiosRequest (NcbPtr) ; 

> 

void NetbiosRecei veDatag ram (NcbPtr, BufferPtrNear, Buffers i ze) 
struct Neb *NcbPtr; 
struct DgStruct *BufferPtrNear; 

USGI BufferSize; 

struct DgStruct far *Buf ferPtrFar; 


ClearNcb(NcbPtr) ; 
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Listing 12-1. (cont.) 


NcbPtr->NcbCommand = NETBIOS_RECEIVE_DATAGRAM + N0_WAIT; 

BufferPtrFar = (struct DgStruct far *) Buf ferPtrNear; 

NcbPtr->NcbBufferOf fset = (char *) FP_0FF(Buf ferPtrFar) ; 
NcbPtr->NcbBufferSegment = (USGI) FP_SEG(Buf ferPtrFar) ; 

NcbPtr->NcbLength = BufferSize; 

NcbPtr->NcbNum = ConferenceNameNum; 

NetbiosRequest (NcbPtr) ; 

> 

void NetbiosCanceLNcb(NcbPtrNear) 
struct Neb *NcbPtrNear; 

struct Neb CancelNcb; 

struct Neb far *NcbPtrFar = (struct Neb far *) NcbPtrNear; 
if (NcbPtrNear->NcbCmdCplt == COMMAND_PENDING) { 
ClearNcb(&CanceLNcb) ; 

CancelNcb. NebCommand = NETBIOS_CANCEL_WAIT_ONLY; 

CancelNcb. NebBufferOffset = (char *) FP_OFF(NcbPtrFar) ; 
CancelNcb. NebBufferSegment = (USGI) FP_SEG(NcbPtrFar) ; 

NetbiosRequest (SCancelNcb) ; 

> 

> 

void NetbiosRequest (NcbPtrNear) 
struct Neb *NcbPtrNear; 

union REGS InRegs, OutRegs; 

struct Neb far *NcbPtrFar = (struct Neb far *) NcbPtrNear; 

NcbPtrNear“>NcbLanaNum = 0; /* force to adapter zero */ 

segread(&SegRegs) ; /* init the segment regs */ 

SegRegs.es = FP_SEG(NcbPtrFar) ; 

InRegs. x.bx = FP_OFF(NcbPtrFar) ; 

int86x(NetbiosInt5C, &InRegs, &0utRegs, &SegRegs); 
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Listing 12-1. (cont.) 

> 

/it Perfunctory Routines */ 

void LogoO 
{ 

CLsO; 

printfC'*- NETBIOS Online Conference"); 

printfC © Copyright 1988 W. David Schwaderer -★Xn") ; 

> 

int EditArgs(argc, argv) 
int argc; 
char ★argvl]; 

T 

if (argc != 3) { 

ExpLainO ; 

printf <"\n\nIncorrect number of parameters..."); 
return FAILURE; 

> 

if (strlenCargvCI ]) > 15) { 

ExpLainO ; 

printf ("\n\nConference name \"%s\" is too long...", 

argvCI ]); 

return FAILURE; 

> 

if (!strcmp(argv[2], "MONITOR!")) -C 

printf ("\n\nNo no. ..try another handle please..."); 
return FAILURE; 

> 

if (strlen(argv[2]) > 15) i 
ExplainO ; 

printf ("\n\nHandle \"%s\" is too long...", 
argv[2]) ; 

return FAILURE; 

> 

return SUCCESS; 

> 

void ExplainO 
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Listing 12-1. (cont.) 

printf (''\nusage : cb conference handle”); 

printf (”\n\t\tconference: The conference name...”); 

printf (”\n\t\thandle: Your personal pseudonym...”); 

> 

void ExitNowO 

printf (”\n\n\x07Program ending because of errors. . .\n”) ; 
exitd); 

> 

/if 0IOS Requests */ 

void ClsO 

ScrollScreen(R0W_1, ROW_25, ENTIRE^SCREEN) ; 

Set CursorPos i t i on (ROW J , C0LUMN_1 ) ; 

> 

void Scrol IScreenCBegi nRow, EndRow, RowCount) 

USGI BeginRow, EndRow, RowCount; 

union REGS InRegs, OutRegs; I* defined in dos.h */ 

InRegs.h.ah = SCROLL^UP; /* scroll up request */ 

InRegs. h.al = RowCount; /* how many lines */ 

InRegs. h.ch = BeginRow; /* top left corner */ 

InRegs. h. cl = COLUMNJ; 

InRegs. h.dh = EndRow; /* lower right corner */ 

InRegs. h.d I = C0LUMN_80; 

InRegs. h.bh = NORMAL_.ATTRIBUTE; /* fill attribute */ 
int86(BI0S^VIDE0_REQUEST, SlnRegs, &0utRegs); 

> 

void FetchCursorPositionO 

union REGS InRegs, OutRegs; /* defined in dos.h */ 

InRegs.h.ah = FETCH^CURSOR^POSITION; /* set cursor */ 

InRegs. h.bh = PAGE__ZERO; /* page number */ 


int86(BI0S_VIDE0^REQUEST, SlnRegs, SOutRegs); 
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Listing 12-1. (cont.) 

CurrentRow = OutRegs.h.dh; /* set row */ 

CurrentColumn = OutRegs.h.dL; /* set column */ 

> 

void SetPreviousCursorPosi tionO 

SetCursorPosi tionCCurrentRow, CurrentColumn) ; 

> 

void Set CursorPosit ion (Row, Column) 

USGI Row, Column; 

union REGS InRegs, OutRegs; /* defined in dos.h */ 

InRegs.h.ah = SET^CURSOR_POSITION; /* set cursor */ 

InRegs. h.bh = PAGE_ZER0; /* page number */ 

InRegs. h.dh = Row; /* set row */ 

InRegs. h.dl = Column; /* set column */ 

int86(BI0S_VIDE0_REQUEST, &InRegs, &OutRegs); 

> 

The program is not only fun to use but exhibits techniques required by 
datagram applications. Because it is lengthy, only significant portions 
will be described. The remaining portions should closely resemble pre- 
viously described programs. 


The main( ) Function 

The main( ) function begins by invoking Logo( ) which clears the screen 
and presents a logo on the first display line. Then, main( ) calls EditArgs( ) 
to validate the input parameters. If they are not acceptable, main( ) exits 
by invoking ExitNow( ). Otherwise, it initializes the global variables Con- 
ferenceNamePtr and UserNamePtr. 

Next, main( ) calls AddConferenceName( ) which adds the confer- 
ence name (the first command-line parameter) as a group name. If the 
Add Group Name command is successful, main( ) calls AddUserName( ) 
which adds the requested user’s name (the second command-line param- 
eter) with an Add Name command. A unique name is useful here in an 
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attempt to prevent conference imposters. (Note that user pseudonyms 
such as RocketMan and RedRooster may significantly add to the LAN 
conferencing experience.) 

Users are allowed to participate in the conference when main( ) in- 
vokes the primary processing routine Participate( ). When the user even- 
tually depresses the ESC key, Participate( ) exits back to main( ) which 
clears the screen, cancels any pending Receive Datagrams, and deletes 
both the conference and user name before ending execution. 


£ditArgs( ) 

EditArgs( ) expects two command-line arguments, each of which is 15 
characters or less. In addition, EditArgs does not allow the user name to 
be '‘MONITOR!.” This character string is reserved by the program for su- 
pervisory use in announcing entries into and departures from confer- 
ences by individual users. Note that all 15 characters are significant. 


NetBIOS Add Name Processing Routines 

AddConferenceName( ) and AddUserName( ) both invoke NetbiosAdd- 
Name( ) to add the requested conference and user names, respectively. 
Unlike the previous NetBIOS Add Name routine, NetbiosAddName con- 
tains two formal parameter declarations, when the second parameter in- 
dicating whether the name is a group or unique name. If there is a 
problem adding any name, NetbiosAddName returns an illegal NcbNum 
(OOh), indicating there has been an error. 


Participate^ ) 

Participate( ) begins by displaying the requested user and conference 
names. It then invokes IssueReceiveDatagramRequests( ) which uses 
each Neb in the InDgNcb array to issue a Receive Datagram request. Each 
Neb in this array has its receive buffer in the corresponding InDg struc- 
ture array. 

Participate( ) then calls EmitUserStatusMsg( ) and passes a parameter 
causing each existing participant within the selected conference to re- 
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ceive notification that a new participant has joined the conference. Be- 
cause newly joining participants have previously issued conference 
Receive Datagrams, they receive the message as well (no conference lurk- 
ers here!). 

Participate( ) calls SetUpInputLine( ) which clears display line 25 and 
initializes the program’s keystroke-accumulation buffer. It then enters 
the primary program-processing loop which terminates only when the 
variable Participating becomes FALSE (when ESC is depressed by the 
user). Within this loop, the program constantly flips between processing 
received datagrams from the other conference participants and process- 
ing the keyboard. 

When the user finally depresses the ESC key, the loop ends and Par- 
ticipate( ) calls EmitUserStatusMsg( ), passing a parameter causing each 
participant within the selected conference to receive notification that 
the user has departed the conference. Participate( ) spins on the transmis- 
sion of the departure message until it completes to avoid leaving a Send 
Datagram command pending after program termination. 


ServiceDatagramNcbs( ) 

ServiceDatagramNcbs( ) checks the InDgNcb array to see if any Receive 
Datagram commands have completed. NetBIOS conveniently completes 
these Nebs in the order they were used (IssueReceiveDatagramRe- 
quests( ) issued the Receive Datagrams using Neb elements InDgNcb[0], 
InDgNcbfl], . . . InDgNcb[MAX_NCBS]), so the routine needs only to 
check the first Neb it discovered was not complete the last time it 
checked. 

This InDgNcb array element-checking is all done modulo MAX 
_NCBS. The variable StartingNcb is defined as a static variable so that the 
current starting point is remembered between routine entries and the en- 
tire process is assisted by the TARGET_NCB preprocessor definition. 

If an Neb has completed, ServiceDatagramNcbs( ) invokes Process- 
ReceivedDatagram( ) to display the message. ServiceDatagramNcbs( ) 
then reuses the Neb to issue another Receive Datagram command before 
checking the next Neb for completion. This process continues until a 
pending Neb is found, the StartingNcb variable is updated, and the rou- 
tine returns to Participate( ). 

Note it is possible for all Nebs to be completed at a given workstation 
when another conference workstation transmits a datagram. In this case, 
the datagram is not received by the lethargic workstation. The only pos- 
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sible solution is to increase the number of Nebs in the InDgNcb array for 
that workstation. However, even this may not work because of restric- 
tions on the maximum number of outstanding commands, among other 
reasons. 

In the final analysis, datagram communication works well in rela- 
tively light message-rate situations. Its flexibility comes at the price of 
data integrity problems in the general case. 


ProcessReceivedDatagram( ) 

ProcessReceivedDatagram( ) checks the return code of the Neb that re- 
quires processing. If the return code is not zero, ProcessReceived- 
Datagram( ) returns without attempting to process the received 
datagram. Otherwise, ProcessReceivedDatagram( ) calls FetchCur- 
sorPosition( ) to save the current screen cursor position and scrolls the 
screen from line 1 (the second line) to line 24. It then displays the name 
of the user that transmitted the message and the user’s message. 

Before exiting, ProcessReceivedDatagram( ) calls SetPreviousCur- 
sorPosition( ) to restore the screen cursor to the position it had when 
ProcessReceivedDatagram( ) was entered. 


ServiceKeyboard( ) 

ServiceKeyboard( ) checks to see if there have been any keystrokes since 
it was last invoked. If not, it exits. Otherwise, it reads the keystroke and 
examines it for significance: 

• If a function key has been pressed or some other combination 
keystroke results in a BIOS extended keystroke (e.g., Alt-1), the 
keystroke is ignored. Note that this requires clearing the associ- 
ated second keystroke value with another keyboard read. 

• If the backspace key was pressed, the last displayed keystroke 
character is erased and the accumulated keystroke buffer and 
buffer length are adjusted appropriately. 

• If the ESC key was pressed, the Participating variable is set to 
FALSE. 

• If the ENTER key was depressed, the accumulated keystrokes are 
sent as a message by calling SendKeyboardMsg( ). 



Chapter 12: LAN Conferencing 


137 


• Otherwise, the keystroke value is given to ApplyKeystroke( ) for 
processing (accumulation). 


SendKeyboardMsg( ) 

SendKeyboardMsg( ) clears out the Send Datagram buffer area before 
copying the user name and message into the buffer. It then calls Netbios- 
SendDatagram( ) to send the conference datagram. Finally before exit- 
ing, it calls SetUpInputLine( ) to initialize the program keystroke 
accumulation buffer. 

Note that SendKeyboardMsg( ) does not check to see if the last Send 
Datagram command is still pending. Since all Send Datagram commands 
in this program use the same Neb, this could be a serious program error. 
However, NetbiosSendDatagram( ) does this at entry. In addition, Netbi- 
osSendDatagram( ) also uses other logic not used in previous discus- 
sions, so you may wish to examine it a bit closer than other functions. 


ApplyKeystroke( ) 

ApplyKeystroke( ) first checks to see that the maximum number of key- 
strokes have not been accumulated. If they have, ApplyKeyStroke( ) 
beeps the workstation and returns. Otherwise, it checks to see that the 
character is a valid displayable ASCII character. If so, ApplyKeystroke( ) 
appends that keystroke to the accumulated ones and displays the charac- 
ter before returning. 
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This chapter discusses two applications that provide file transfer capabil- 
ity via a NetBIOS session. One application, SEND.C in Listing 13-1, trans- 
mits a file. The other, RECEIVE. C in Listing 13-2 receives the file. While 
the programs only allow one file transmission before they both end exe- 
cution, they are not difficult to extend to provide multiple-file transfers 
within a session, perhaps using PC-DOS wildcard file specifications. But 
that topic is beyond the scope of this discussion and is left as a reader 
exercise. 


Listing 13 - 1 . SEND.C 

#define LINT_AR6S 

^include <dos.h> 

^include <stdio.h> 

//include ’’netbiosZ.h" 

//if defined(LINT_AR6S) 

extern int mainCint argc,char * *argv); 

extern int AddSessionNameCchar *NamePtr); 

extern int CreateSession(void) ; 

extern void ProcessFi le(void) ; 

extern void Transmi tFi LeCstruct _iobuf *FiLePtr); 
extern void Termi nateSession(void) ; 
extern void DeleteSessionNameCchar ★NamePtr); 
extern void ClearNcbCstruct Neb ^NebPtr); 
extern unsigned char NetbiosAddNameCchar *Name); 
extern void NetbiosCalKstruct Neb *NcbPtr); 
extern void NetbiosDeleteNameCchar *Name); 

extern void NetbiosHangUpCstruct Neb *NcbPtr, unsigned char TargetLsn); 


m 
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Listing 13-1. (cont.) 

extern void NetbiosSendCstruct Neb *NcbPtr); 
extern void NetbiosRequest (struct Neb *NcbPtrNear) ; 
extern void Logo(void); 

#endi f 

#define SESSION_NAME__TERMINATOR 0x88 

USGC SessionLsn; 

struct Neb ControLNcb, XmitNcb; 

struct SessionMsg XmitBLock; 

/* 1234567890123 */ 
char SendNameC] = "WDS-Send~Fi le"; 
char ReevNameC] = "WDS-Reev-Fi le"; 

int main(argc,argv) 
int arge; 
char *argvC]; 

{ 

LogoO; 

if (AddSessionName(SendName)) { 

if (CreateSessionO) { 

ProcessFi leO ; 

TerminateSessionO; 

> 

DeLeteSessionName(SendName) ; 

> 

printf (''\n\nProgram ending. . .\n") ; 
return 0; 

> 

int AddSessionName(NamePtr) 
char *NamePtr; 

printf ("\n\nAdding the session name %s...", NamePtr); 


if (NetbiosAddNameCNamePtr) == ILLEGAL NAME NUM) 
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Listing 13-1. (cont.) 


return FAILURE; 

else 

return SUCCESS; 

> 


int CreateSessionO 

{ 

printf (''\n\nCal Ling to create the session..."); 

NetbiosCal L C&ControlNcb) ; 

if ( ! ControlNcb.NcbRetCode) -C 

printf ("session successfully created..."); 

SessionLsn = ControlNcb.NcbLsn; 
return SUCCESS; 

> else { 

printf ("session not created error 0x%02X ", 

ControlNcb.NcbRetCode) ; 

return FAILURE; 

> 

> 

void ProcessFi leO 

FILE *FilePtr; 
char Fi leNameClOO]; 

printf ("\n\nPlease enter the file name to send ==> "); 
gets(Fi leName) ; 

if (Fi lePtr = fopen(Fi LeName, "rb")) i 
Transmit Fi le(Fi lePtr) ; 
fclose(Fi lePtr) ; 

> 

> 

void TransmitFi le(Fi lePtr) 

FILE *Fi lePtr; 

US6I ReadCount, ProcessFlag = TRUE, Count = 0; 

USGL TransmissionSize = 0; 
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Listing 13-1. (cont.) 

printf (’'\nFi le Transfer beginning. .. \n") ; 

while (ProcessFlag == TRUE) { 

ReadCount = freadC Xmi tBlock.Text, si zeof (char) , 

sizeofCXmit Block. Text) , Fi lePtr) ; 

if ( ! ferrorCFi lePtr)) { 

if ((XmitBlock.TextLength = ReadCount) != 0) i 

printf ("NnTransmitting block %3u...size = %u'', 

++Count, XmitBlock.TextLength); 


NetbiosSendC&XmitNcb) ; 

if (Xmi tNcb.NcbRetCode) { 

printf ("\n\nSend error %02X...", 

Xmi tNcb.NcbRetCode) ; 
ProcessFlag = FALSE; 

> else { 

TransmissionSize += XmitBlock.TextLength; 

> 

> 


i f (feof (Fi lePtr)) { 

printf (''\n\nFi le Transmi tted. . .”) ; 
ProcessFlag = FALSE; 


> else { 

printf (''\n\nError reading file..."); 
ProcessFlag = FALSE; 

> 

> 


> 


printf ("\n\nTotal transmission size = %lu bytes...", 

TransmissionSize) ; 


void TerminateSessionO 
i 


printf ("\n\nHanging Up on the session..."); 
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Listing 13-1. (cont.) 
NetbiosHangUp(&ControLNcb, SessionLsn) ; 

if ( ! ControLNcb.NcbRetCode) 

printfC'the Hang Up was successful.."); 

else 

printfC'the Hang Up was not successful.."); 

> 

voi d De leteSessi onName(NamePtr) 
char *NamePtr; 

printf ("\n\nDeleting the session name %s...", NamePtr); 
NetbiosDeleteName(NamePtr) ; 

> 

/* Netbios Requests 

struct SREGS SegRegs; /* defined in dos.h */ 

void ClearNcb(NcbPtr) 
struct Neb *NcbPtr; 

i nt i ; 

char *CharPtr = (char ★) NcbPtr; 

for ( i = 0; i < sizeof (ZeroNcb); i++ ) 

*CharPtr++ = '\x00'; 

> 

US6C NetbiosAddName(Name) 
char *Name; 

struct Neb AddNameNcb; 

ClearNcbC&AddNameNcb) ; 

AddNameNcb. NebCommand = NETBIOS_ADD^NAME; 

strnepy (AddNameNcb. NcbName, Name, strlen(Name) ) ; 
AddNameNcb. NebNamedS] = SESSION_NAME_TERMINATOR; 

Netbi osRequest (^AddNameNcb) ; 




if (! AddNameNcb. NebRetCode) -C 
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Listing 13-1. (cont.) 

printf . .the add-name was successful..."); 
return AddNameNcb.NcbNum; 

> else { 

printf (".. .unsuccessful add-name. . .error %02X...", 

AddNameNcb.NcbRetCode) ; 

return ILLEGAL_NAME_NUM; 

> 

> 

void NetbiosCal I (NcbPtr) 
struct Neb *NcbPtr; 

ClearNcb(NcbPtr) ; 

NcbPtr->NcbCommand = NETBIOS_CALL; 

St rncpy(NcbPtr->NcbCal IName, ReevName, str len(RecvName) ) ; 
NcbPtr->NcbCallName[15] = SESSION_NAME_TERMINATOR; 

strncpy(NcbPtr->NcbName, SendName, str len(SendName) ) ; 
NcbPtr->NcbNameC15] = SESSION_NAME_TERMINATOR; 

NcbPtr->NcbSto = 30; /* 15 second time out */ 

NcbPtr->NcbRto = 30; /* 15 second time out */ 

NetbiosRequest (NcbPtr) ; 

> 

void NetbiosDeleteName(Name) 
char *Name; 

struct Neb DeleteNameNcb; 

ClearNcbC&DeleteNameNcb) ; 

DeleteNameNcb. NebCommand = NETBIOS_DELETE_NAME; 

strncpyCDeleteNameNcb.NcbName, Name, strlen(Name)) ; 
DeleteNameNcb. NcbNameC15] = SESSION_NAME_TERMINATOR; 

NetbiosRequest (&DeleteNameNcb) ; 

> 
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Listing 13-1. (cont.) 

void NetbiosHangUpCNcbPt r, TargetLsn) 
struct Neb *NcbPtr; 

USGC TargetLsn; 

ClearNcb(NcbPtr) ; 

NcbPtr->NcbCommand = NETBIOS_HANG_UP; 

NcbPtr->NcbLsn = TargetLsn; 

NetbiosRequest (NcbPtr) ; 

> 

void NetbiosSend(NcbPtr) 
struct Neb *NcbPtr; 

struct SessionMsg far *Buf ferPtrFar; 

ClearNcb(NcbPtr); 

NcbPtr->NcbCommand = NETBIOS_SEND; 

NcbPtr->NcbLsn = SessionLsn; 

BufferPtrFar = (struct SessionMsg far *) &XmitBLock; 

NcbPtr”>NcbBufferOffset = (char *) FP_OFF(BufferPtrFar) ; 
NcbPtr->NcbBuf ferSegment = (USGI) FP_SEG(Buf ferPtrFar) ; 

NcbPtr->NcbLength = sizeof (XmitBlock); 

NetbiosRequest (NcbPtr) ; 

> 

void NetbiosRequest (NcbPtrNear) 
struct Neb *NcbPtrNear; 

union REGS InRegs, OutRegs; 

struct Neb far *NcbPtrFar = (struct Neb far *) NcbPtrNear; 
NcbPtrNear~>NcbLanaNum = 0; /* force to adapter zero */ 


segread(&SegRegs) ; 


/* init the segment regs */ 
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Listing 13-1. (cont.) 

SegRegs.es = FP_SEG(NcbPtrFar) ; 

InRegs.x.bx = FP_OFF(NcbPtrFar) ; 

int86x(NetbiosInt5C, &InRegs, &OutRegs, SSegRegs); 

> 

void LogoO 

printf ("\nNETBI0S Sample Send Program"); 
printfC" © Copyright 1988 W. David Schwaderer") ; 

> 

Listing 13-2. RECEIVE.C 

^define LINT_ARGS 

^include <dos.h> 

^include <stdio.h> 

^include "netbios2.h" 

#if defined(LINT_ARGS) 

extern int mainCint argc,char * *argv); 

extern int AddSessionNameCchar *NamePtr); 

extern int CreateSession(void); 

extern void ProcessFi le(void) ; 

extern void Recei veFi leCFILE *FilePtr); 

extern void DeleteSessionNameCchar *NamePtr); 

extern void TerminateSession(void) ; 

extern void C LearNcbCst ruct Neb *NcbPtr); 

extern USGC NetbiosAddNameCchar *Name); 

extern void NetbiosLi stenCstruct Neb *NebPtr); 

extern void NetbiosDeleteNameCehar *Name); 

extern void NetbiosHangUpCstruet Neb *NebPtr, USGC TargetLsn); 
extern void NetbiosRecei veCstruet Neb ★NebPtr); 
extern void NetbiosRequest (struet Neb *NebPtrNear) ; 
extern void Logo(void); 

#endi f 

#define SESSION^NAME_TERMINATOR 0x88 
USGC SessionLsn; 
struet Neb ControLNcb, XmitNeb; 
struet SessionMsg XmitBloek; 



Chapter 15: C File Transfer Applications 


147 


Listing 13-2. (cont.) 


/* 1234567890123 */ 
char SendNameC] = "WDS-Send-Fi le"; 
char RecvNameC] = "WDS-Recv-Fi le"; 

int main(argc,argv) 
int argc; 
char *argvC]; 

Logo ( ) ; 

if (AddSessionName(RecvName)) { 

if (CreateSessionO) 

ProcessFi leO ; 

DeleteSessionName(RecvName) ; 

> 

printf ("\n\nProgram ending. . .\n"); 
return 0; 

> 

int AddSessionName(NamePtr) 
char *NamePtr; 

printf ("\n\nAdding the session name %s...", NamePtr); 

if (NetbiosAddName(NamePtr) == ILLEGAL_NAME_NUM) 
return FAILURE; 

else 

return SUCCESS; 

> 

int CreateSessionO 

printf ("\n\nLi stening to create the session..."); 

NetbiosLi sten(&ControLNcb) ; 

if ( ! ControlNcb.NcbRetCode) < 

printf ("session successfully created..."); 
SessionLsn = ControlNcb.NcbLsn; 
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Listing 13-2. (cont.) 


return SUCCESS; 

> else -C 

printf ("session not created. . .error 0x%02X...", 

ControlNcb.NcbRetCode) ; 

return FAILURE; 

> 


void ProcessFi leO 

FILE *FiLePtr; 
char Fi leNameClOO] ; 

printf ("\n\nPlease enter the file name to receive ==> "); 
getsCFi leName); 

if (FilePtr = fopenCFi LeName, "wb")) { 

ReceiveFi Le(Fi lePtr); 
fcloseCFi LePtr); 

> 

> 

void ReceiveFi LeCFi LePtr) 

FILE *Fi LePtr; 

USGI WriteCount, ProcessFLag = TRUE, Count = 0; 

USGL Transmi ssionSize = 0; 

printf ("\nFi Le transfer beginning. . .\n") ; 

while (ProcessFLag == TRUE) { 

NetbiosRecei ve(&Xmi tNcb) ; 

if (XmitNcb.NcbRetCode) { 

printf ("\n\nReceive error %02X...", XmitNcb.NcbRetCode); 
TerminateSessionO ; 

ProcessFLag = FALSE; 

> else { 

printf ("\nSuccessfuL Ly received block %3u...size = %u", 
++Count, Xmi tBLock.TextLength) ; 
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Listing 13-2. (cont.) 

WriteCount = fwriteCXmi tBLock.Text , si zeof (char) , 

XmitBLock.TextLength, Fi LePtr) ; 

if (WriteCount != XmitBLock.TextLength) 

printf (”. . .but only wrote %u bytes !\x07", 

WriteCount) ; 

TransmissionSize += XmitBLock.TextLength; 

> 

> 


> 


printf ("\n\nTotaL transmission size = %Lu bytes...”, 

TransmissionSize); 


void DeLeteSessionName(NamePtr) 
char *NamePtr; 

printf (”\n\nDeLeting the session name %s...”, NamePtr); 
NetbiosDeLeteName(NamePtr) ; 

> 

void Termi nateSessionO 

printf (”\n\nHanging Up on the session...”); 

NetbiosHangUp(&ControLNcb, SessionLsn); 

if ( ! ControLNcb.NcbRetCode) 

printfC'the Hang Up was successful..”); 

else 

printfC'the Hang Up was not successful..”); 

> 

/* Netbios Requests */ 

struct SREGS SegRegs; /* defined in dos.h */ 

void ClearNcb(NcbPtr) 
struct Neb *NcbPtr; 

i nt i ; 

char *CharPtr = (char *) NcbPtr; 
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Listing 13-2. (cont.) 

for ( i =0; i < sizeof (ZoroNcb) ; i++ ) 

★CharPtr++ = *\x00*; 

> 

USGC NetbiosAddNameCName) 
char *Name; 

struct Neb AddNameNcb; 

ClearNcbC&AddNameNcb) ; 

AddNameNcb.NcbCommand = NETBIOS_ADD_NAME; 

strnepy (AddNameNcb.NcbName, Name, strLen(Name)) ; 
AddNameNcb.NcbNamedS] = SESSION_NAME_TERMINATOR; 

Netbi osRequest (SAddNameNcb) ; 

if (lAddNameNcb.NcbRetCode) { 

printf . .the add-name was successful...''); 
return AddNameNcb.NcbNum; 

> else { 

printf (".. .unsuccessful add-name. . .error %02X...", 

AddNameNcb.NcbRetCode) ; 

return ILLEGAL_NAME_NUM; 

> 

> 

void NetbiosHangUpCNcbPtr, TargetLsn) 
struct Neb *NcbPtr; 

USGC TargetLsn; 

T 

ClearNcb(NcbPtr) ; 

NcbPtr->NcbCommand = NETBIOS_HANG_UP; 

NcbPtr->NcbLsn = TargetLsn; 

NetbiosRequest (NcbPtr) ; 

> 

void NetbiosLi sten(NcbPtr) 
struct Neb *NcbPtr; 
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Listing 13-2. (cont.) 


ClearNcb(NcbPtr) ; 

NcbPtr->NcbCommand = NETBIOS_LISTEN; 

strncpy (NcbPtr->NcbCaUName, SendName, strlen(SendName)) ; 
NcbPtr->NcbCaLLName[15] = SESSION_NAME_TERMINATOR; 

strncpy (NcbPtr“>NcbName, RecvName, strLen(RecvName)) ; 
NcbPtr->NcbName[15] = SESSION_NAME_TERMINATOR; 

NcbPtr“>NcbSto = 30; /* 15 second time out */ 

NcbPtr“>NcbRto = 30; /* 15 second time out */ 

NetbiosRequest (NcbPtr) ; 

> 

void NetbiosDeLeteName(Name) 
char *Name; 

struct Neb DeleteNameNcb; 

CLearNcbC&DeLeteNameNcb) ; 

DeleteNameNcb. NebCommand = NETBIOS_DELETE_NAME; 

strnepy (DeleteNameNcb. NcbName, Name, strlen(Name)) ; 
DeleteNameNcb. NcbNameC15] = SESSION_NAME_TERMINATOR; 

NetbiosRequest (SDeleteNameNcb) ; 

> 

void NetbiosRecei ve(NcbPtr) 
struct Neb *NcbPtr; 

*C 

struct SessionMsg far *BufferPtrFar; 

ClearNcb(NcbPtr) ; 

NcbPtr”>NcbCommand = NETBIOS_RECEIVE; 

NcbPtr“>NcbLsn = SessionLsn; 

BufferPtrFar = (struct SessionMsg far *) SXmitBlock; 
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Listing 13-2. (cont.) 


NcbPtr->NcbBufferOffset = (char *) FP_OFF(BufferPtrFar) ; 
NcbPtr->NcbBufferSegment = (USGI) FP_SEG(BufferPtrFar) ; 

NcbPtr->NcbLength = sizeof (XmitBlock) ; 

NetbiosRequest (NcbPtr) ; 

> 

void NetbiosRequest (NcbPtrNear) 
struct Neb *NcbPtrNear; 

{ 

union REGS InRegs, OutRegs; 

struct Neb far *NcbPtrFar = (struct Neb far ★) NcbPtrNear; 

NcbPtrNear->NcbLanaNum = 0; /* force to adapter zero */ 

segread(&SegRegs) ; /* init the segment regs 

SegRegs.es = FP_SEG(NcbPtrFar) ; 

InRegs. x.bx = FP_OFF(NcbPtrFar) ; 

int86x(NetbiosInt5C, &InRegs, &OutRegs, &SegRegs); 

> 

void LogoO 

printf ("\nNETBI0S Sample Receive Program"); 
printfC © Copyright 1988 W. David Schwaderer") ; 

> 


Application Overview 

SEND.C and RECEIVE. C work in tandem to transfer files. They both be- 
gin by adding unique names to their NetBIOS name table. SEND.C uses 
the name WDS-Send-File; RECEIVE uses the name WDS-Recv-File. Both 
names are terminated in the l6th position with a nonzero value, guaran- 
teeing their uniqueness from IBM reserved names. 

If the Add Name commands are successful, both applications attempt 
to establish a session with the other. RECEIVE. C initiates its side of Net- 
BIOS session with a Listen command specifying its unique name as well 
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as the unique name SEND.C uses. The Listen command must be pending 
before the Call command issued by SEND.C times-out. 

The Listen command uses a no- wait option so SEND.C must connect 
to it or the machine executing RECEIVE. C must eventually be rebooted. 
If the SEND.C Call command times-out, simply execute SEND.C again to 
establish the session. After this is done, SEND.C and RECEIVE. C prompt 
their users for the file that is respectively transmitted and received. After 
the users reply to their prompts, perhaps using different names, the data 
transfer begins. Note that each side of the session specifies a 15-second 
time-out in its Listen and Call commands for session Receive and Send 
commands, so users should not wait too long to respond to prompts af- 
ter the other user responds or the session will abort. If it does abort, sim- 
ply run the programs again. 

If any error is detected by a session partner during the transmission 
session, that partner aborts the session using a Hang Up command and 
the other session partner’s Send or Receive command subsequently 
completes with a ‘‘Session Aborted” return code. Otherwise, the session 
continues transferring data using a C structure that contains both data 
and a value indicating how much data actually resides in the area re- 
served for it. This structure is defined in the netbios2.h header file. 

When SEND.C eventually has no more data to transfer, it issues a 
Hang Up command to terminate the session. When RECEIVE. C’s pend- 
ing Receive command completes with an error, it attempts to abort the 
session which no longer exists. The Hang Up command subsequently 
fails with a “Session Closed” error code. 

Everything considered, NetBIOS session communication is very 
easy as Listings 13-1 and 13-2 illustrate. In fact, the program logic to read 
and write the files is nearly as difficult as the actual NetBIOS session 
logic. The sample programs are laced with printf( ) statements that pro- 
vide user feedback as the session continues. These statements also eon- 
siderably reduce any mystery within the programs’ logic, though 
experienced users may find their unnecessarily chatty nature somewhat 
offensive. As much logic as possible is shared between the programs to 
reduce the programming effort even further. Have fun and happy file 
transfers. 




Chapter 14 


Medialess Workstations, RPL, and 
Redirectors 


Medialess workstations, RPL, and redirectors share two common attri- 
butes: 

• Each involves the transfer of data requests (e.g., read, write, etc.) 
from one workstation to another for resolution. 

• Because the data request is performed elsewhere, the possibility 
exists that the data is being used by many other machines, thereby 
causing potential data sharing problems. 


Clients and Servers 

In such situations, requesting machines, referred to as clients, obtain 
data storage and management services from cooperating machines, re- 
ferred to as servers. Usually, clients and servers communicate via a LAN 
connection. Depending on the LAN and the number of clients, it is often 
possible for data requests to be processed faster and more economically 
using a high-performance server rather than slower local storage devices 
at client machines. 


Medialess Workstations 

Medialess workstations are client machines that have no local diskette or 
disk storage. The primary advantage of these machines is their lower cost 
and the natural data security provided by not being able to copy data 
onto a diskette that may enter or leave the establishment. 


155 



156 


Part 11: Support Programming 


Remote Program Load (RPL) 

Medialess workstations typically use RPL to load their operating systems 
into memory. Once loaded, the operating system initializes the worksta- 
tion normally, oblivious to the absence of local disk and diskette devices. 
Subsequent applications similarly execute, unaware of the absence of lo- 
cal storage devices. 


Redirectors 

Redirectors are components that intercept local data requests and redi- 
rect (transfer) them to server machines. In contrast to RPL, which ini- 
tially operates with no operating system present, redirectors operate as 
system extensions. 

Examples of popular redirectors are Microsoft Corporation’s redirec- 
tor in the Microsoft Networks (MS-NET) product and REDIR.EXE used in 
IBM’s PC LAN Program (PCLP). In the OS/2 arena, Microsoft provides a 
redirector in its Microsoft LAN Manager product and IBM includes the 
OS/2 LAN Requestor function in the IBM OS/2 Extended Edition version 
l.I. 


Data Layers 

Figure 14-1 depicts a conceptual representation of the layers that resolve 
data requests within popular PC-DOS machines. This figure clearly illus- 
trates that data requests can be captured at any of three points in their 
processing; 

the INT 21 PC-DOS Interface 

the Block Device Driver Call Interface 

the INT 13 BIOS Interface 


The INT 21 PC-DOS Interface 

The INT 21 PC-DOS interface provides a variety of machine services in- 
cluding data services at the file level. These services open, close, create, 
modify, and erase files based on application program requests. 
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Fig. 14-1. Conceptual view of PC-DOS data request 
processing layers. 

Applications load registers and initialize various data fields with val- 
ues that indicate the type of service requested and which particular file 
or files the request relates to. The application then issues an INT 21 re- 
quest which is intercepted by PC-DOS and acted on. PC-DOS eventually 
returns after performing the task to the best of its ability. 


The Block Device Driver Call Interface 

PC-DOS device drivers are modules that control specific devices. Their 
primary advantage is that they allow programmers to create operating 
systems that are independent of any particular device-specific considera- 
tions. Thus, when a new device replaces another, typically only the spe- 
cific device driver needs to change — not the operating systems that 
support the device. 

There are two types of PC-DOS device drivers: character device driv- 
ers and block device drivers. A common misconception is that character 
device drivers can only handle one-character-at-a-time requests while 
block device drivers can handle blocks of data at a time. 

Character device drivers control the operation of devices such as 
printers, keyboards, displays, etc. Using operating system services such 
as I/O redirection, these devices can be regarded as filelike devices. 
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Block device drivers control the operation of devices such as disks, 
diskette drives, CD-ROM devices, etc. These types of devices support file 
systems. Thus, the primary distinction between character and block de- 
vice drivers is independent of an ability to process blocks of data with a 
single request. 

PC-DOS invokes device driver services using a program-call interface 
that is documented in the PC-DOS Technical Reference Manual. This in- 
terface can be involved, depending on the device, and is beyond the 
scope of this book. For further information on device drivers, consult 
the Manual or Writing MS-DOS Device Drivers (Lai 1987). 


The INT 13 BIOS Interface 

The INT 13 BIOS interface provides the lowest level data service inter- 
face. After loading registers with values that specify the type of request, 
PC-DOS block device drivers issue an INT 13 interrupt request. The reg- 
isters and the significance of their contents are listed in Table 14-1. 


Table 14-1. Interrupt Registers 


Register 

Meaning 

AH 

Request type (reset, read, write, format track, etc.) 

CH 

Cylinder number 

CL 

Sector number 

DH 

Head number 

DL 

Drive Number (0x00 = = > A:, 0x01 = = > B:, etc.) 

ES :BX 

Address of buffer for reads/writes 


After the BIOS performs the requested operation, it follows the fol- 
lowing steps: 

1 . placing the operation final status in the AH register 

2 . placing requested device information (if any) in the CX and DX 
registers 

3. setting the carry flag (CY) to zero or one, respectively, indicating 
request success or failure 

4. returning via a FAR RET 2 instruction that preserves the existing 
flag settings 
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The module that issued the request resumes execution and subsequently 
analyzes the results. 


A Redirector Implementation 

The REDIR.EXE redirector has a set of private interfaces allowing it to 
determine which servers to establish NetBIOS sessions with, and to iden- 
tify which client devices should have their requests forwarded to a 
server. More than one client device can be serviced by a single redirector. 

REDIR.EXE operates at the INT 21 PC-DOS interface by trapping INT 
21 PC-DOS requests and inspecting them. If a request is not for a device 
the redirector is handling, the request is passed on to PC-DOS for local 
processing. Otherwise, the redirector transmits the request to the server 
using the Server/Redirector protocol via a Server Message Block (SMB). 
The May 1985 IBM Personal Computer Seminar Proceedings (volume 2, 
number 8-1) document describes this protocol, which is beyond the 
scope of this discussion. 

The primary advantage of a redirector implementation is that it al- 
lows servers to provide extensive services for clients because client re- 
quests are intercepted at a very high level. As an example, the REDIR.EXE 
redirector provides a variety of data sharing support. However, redirec- 
tor implementations typically require significant programming efforts 
and you must have a very intimate knowledge of PC-DOS before you can 
write implementations that function transparently to applications. 


A Block Device Driver Implementation 

Block device drivers allow client workstations to specify disk requests 
for a specific virtual drive to be passed to the device driver for forwarding 
to, and processing by, a server. The target server and device are specified 
during the installation of the device driver. The installation process 
should also establish a communication session between the client and 
server workstation. The disk space provided by the server to the client is 
referred to as a Remote Virtual Disk (RVD). 

In contrast to a redirector, a block device driver can typically service 
requests only for a single device. Data sharing facilities are also limited 
but can be crudely implemented by returning a “Media Changed” result 
to client PC-DOS Media Check function calls whenever the server indi- 
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cates data has changed at the server. Client machines receiving such a 
signal flush their buffers and reread the device to obtain the correct infor- 
mation. (See Lai (1987) and the PC-DOS Technical Reference Manual) 


The INT 13 BIOS Interface 

The INT 13 BIOS interface presents data requests at the lowest possible 
interface — the BIOS interface. Because all local device requests result in 
INT 13 calls, modules that operate at this level can forward requests for 
several devices to one or more servers using preestablished NetBIOS ses- 
sions. These modules may be PC terminate-and-stay-resident (TSR) pro- 
grams or adapter RPL logic. These modules have virtually no knowledge 
of why a given request is being issued because the accompanying infor- 
mation is too scanty to make a determination. For example, is a sector- 
read request part of a sequential read for a fragmented data file on the 
server disk, or is it simply a read for a sector in another data file? While a 
redirector can easily determine this, modules operating at the INT 13 
level cannot. 

A module operating at the INT 13 level can make very informed deci- 
sions regarding which server disk sectors should be cached locally be- 
cause it can monitor the media access- patterns. On the other hand, a 
redirector operates at too high a level to enjoy this degree of media access 
visibility. 


A NetBIOS RPL Implementation — Or How Does PC-DOS Get in 
There? 


The original PC Network (LANA) card provides the only NetBIOS RPL 
capability within the IBM LAN product line. All other adapters provide 
RPL services at the DLC level. However, the process is necessarily similar 
for all RPL machines. 

The LANA adapter BIOS is entered during the final phase of the PC 
BIOS initialization process. Before returning to BIOS’, the adapter BIOS 

1 . initializes the adapter protocol logic 

2. saves the current ROM BASIC interrupt vector (INT 18) value 
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3. replaces the ROM BASIC interrupt vector with a new value that 
points inside the adapter’s BIOS 

Eventually, BIOS attempts to load a boot sector from the A: diskette 
drive. If the attempt fails, it attempts to load one from the C; disk drive. If 
that fails, BIOS issues an INT 18 request in an attempt to invoke ROM 
BASIC, which causes the microprocessor to begin executing the adapter 
BIOS’s RPL logic. 


Entering the RPL Logic 

The RPL logic first restores the ROM BASIC interrupt vector to the value it 
previously saved. Next, the adapter allocates the top 1 K of memory for its 
use and builds an Neb there. It then issues an Adapter Status command to 
fetch the permanent node name. Finally, it checks to see if the LANA’s W 1 
jumper has been removed. If not, the adapter issues the ROM BASIC in- 
terrupt, permanently giving control to ROM BASIC. 

If jumper W1 has been removed on the LANA card, the logic issues a 
NetBIOS Reset command, specifying 32 sessions and 32 pending com- 
mands. Next, it issues a NetBIOS Call command to the network name 
IBMNETBOOT (ten contiguous capital letters followed by six binary 
zeros) using its own permanent node name and NebSto and NebRto val- 
ues of 240 (120 seconds). 

If the Call eommand is not successful, the logic issues the ROM BA- 
SIC interrupt, permanently giving control to ROM BASIC. Otherwise, a 
boot server exists on the network that should be able to help the client 
machine boot. Thus, the client adapter saves the current setting of the 
INT 13 interrupt vector and replaces it with another vector that points at 
its INT 13 redirection logic and sets an indicator that RPL is active. 


The Initial INT 13 Reset Command 

Next, the RPL logic issues an INT 13 Reset eommand for some undeter- 
mined drive number (DL is not set). This drives the adapter redirection 
logic that first checks to see that the request code in the AH register does 
not have a value of 0x05, 0x06, 0x07, OxOA, or OxOB. 

If the command is one of the unwanted eommands, a value of 0x01 is 
loaded into the AL register and the carry flag is set indicating failure. Oth- 
erwise, the logic checks to see if redirection is active. If not, the request 
is passed to the original INT 13 entry point whose value was previously 
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saved. Since a reset request command has an AH value of 0x00, and RPL 
is active for the sake of this discussion, the logic builds a message from 
the register settings and sends it to the RPL server using the existing Neb 
in high memory over the previously created session (the NcbLsn must 
necessarily have a value of one). 

Request Message Format 

This message is eleven bytes long and has the following format: 


1 AX 1 CX 1 DX 1 ES 1 BX 1 ?? 1 


+0 +2 +4 +6 +8 +10 

Di spLacement 

The eleventh byte (byte 10) is uninitialized and provides an area to hold 
the returning carry flag indicator that the server must return. 


Write Requests (AH = = 0x03) 

At this point, the redirection logic inspects the AH register’s request 
code. If it specifies a write, the redirection logic computes the size of the 
data from the register settings (assuming 512 bytes per sector) and sends 
the data beginning at the memory location pointed at by the ES :BX regis- 
ter pair with a Send command. It then issues a Receive for 11 bytes to 
obtain the register values returned by the server. 


Read Requests (AH = = 0x02) 

If the request specifies a read, the logic issues a Receive command for an 
11-byte message. This returning message contains the returned registers 
from the server. If the read operation was successful at the server, the 
data was transmitted appended to the registers. This means the Receive 
must complete with an error code of 0x06 (message incomplete) if the 
read operation was successful at the server. 

The logic computes the size of the remaining message from the origi- 
nal registers and issues another receive for the pending data. The data 
buffer is specified by the ES:BX register. Otherwise, the read operation 
was unsuccessful at the server and no data is forthcoming. 
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Other Requests 

Because the request was for a reset, the redirection logic simply issues a 
Receive command for 11 bytes to obtain the register values the server 
must always return. Thus, regardless of the command, the redirection 
logic always receives register values before returning to the RPL logic. 


Returning from the Redirection Logic 

Before returning to the RPL logic, the redirection code loads the correct 
registers from the register values returned by the server. Next, it sets the 
carry flag based on the contents of the 11 th byte (byte 10). If this byte has 
a value of 0x00, the carry flag is cleared. Otherwise, the carry flag is set 
indicating a problem with the request. Finally, the redirection logic re- 
turns via a FAR RET 2 instruction that preserves the flag settings. 


Loading the Boot Record 

Remembering that the redirection logic was originally entered as a result 
of the RPL logic’s issuing a BIOS INT 13 reset command, control returns 
to the RPL logic. The RPL logic then issues an INT 13 request after setting 
the register values listed in Table 14-2. This request specifies that the 
server send a boot record. However, the server only needs to have a data 
file created from a bootable diskette. This type of data file is referred to as 
a diskette image. 


Table l4-2. Interrupt Register Values 


Register 

Value 

Meaning 

AH 

0x02 

Read request specified 

AL 

0x01 

Read one sector 

CH 

0x00 

Read cylinder (track) number zero 

CL 

0x01 

Read sector number one 

DH 

0x0000 

Use head number zero 

DL 

0x0000 

Use Drive A: 

ES:BX 

0x0000:0x7C00 

Put the data at 0000: 7 COO 


Using the register settings that arrive from the client, the server only 
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needs to calculate a displacement into the diskette image data file to find 
the correct 512 bytes to send. Once located, the data is transmitted to the 
client, appended to the 11-byte header that contains the returning regis- 
ter values. 


Booting Up 

Once the boot record arrives safely, the client machine jumps to location 
0000 :7C00 and begins executing the boot record. If the server is slightly 
sophisticated, the boot record it initially transmits could actually be a 
small program that contains a short list of diskette images the client can 
select to actually boot from. 

The program can present the list as a menu and allow the user to se- 
lect the appropriate image. After selection, the bogus boot record can 
relocate some of its logic to a different area of memory. This logic sends 
the selection to the server and issues another request for a boot record. 
Since the server knows which diskette image to use, it transmits the ac- 
tual boot record from the selected diskette image. 

The standard boot process now occurs: 

1. The boot record begins issuing read requests to load PC-DOS. 
These requests are intercepted by the adapter redirection logic 
and forwarded to the server for processing. 

2. The diskette image’s CONFIG.SYS is processed. 

3. The diskette image’s AUTOEXEC.BAT is executed. 

Eventually, the client machine can execute a program such as the IBM 
PC LAN Program that allows it to access network servers. After doing so, 
it is probably appropriate to end the session with the RPL server so the 
server can reuse the session table entry for another client machine. (Note 
that a slightly sophisticated RPL server can service many client machines 
simultaneously, each using its own diskette image.) 


Unlinking from an RPL Server 

Since an RPL session must have an NcbLsn value of one at a client ma- 
chine, it would be easy to issue a Hang Up command specifying an 
NcbLsn value of one. However, the redirection logic would indicate that 
RPL was still active. 
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If the client machine actually had an A: diskette drive, it would not be 
able to use it because the redirection logic would continue to attempt to 
redirect all INT 13 requests over the nonexistent session. To avoid this 
problem, NetBIOS provides the Unlink command. 


The Unlink Command 

The Unlink command is trapped by the NetBIOS interface and passed to 
special logic if RPL is still active. Otherwise, the command is ignored but 
returns with a zero return code. The special logic 

• issues a Hang Up command for the RPL session 

• releases the memory that was allocated at the beginning of the 
RPL logic execution 

• resets the RPL active indicator to indicate that RPL is not active 

However, all INT 13 requests must continue to enter the redirection logic 
because the INT 13 interrupt vector cannot be reset to its original BIOS 
setting in case other TSRs may have captured the vector during the boot 
process. The redirection logic continues to be driven even though it no 
longer performs any useful function. It simply passes the requests to the 
original INT 13 routines when it detects that RPL is no longer active. Fi- 
nally, because the Unlink is tied to the LANA NetBIOS RPL, it is easy to 
see that most NetBIOS coders will never have a requirement to use the 
command. However, most NetBIOS implementations honor the com- 
mand as a compatibility legacy. 

The PC Network Technical Reference Manual has sample programs 
that illustrate an RPL server program and provide a utility to build disk- 
ette images. Since the programs are provided assembly listings, they pro- 
vide an educational way to learn the RPL process. 
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CRC Fundamentals 


LAN adapters typically provide transmission techniques to verify that 
messages traverse the LAN’s media without error. However, not all LAN 
nodes and their adapters have the necessary hardware to guarantee that 
messages are transferred between the LAN adapter and the node’s mem- 
ory without error. 

For example, many LAN adapters do not have parity checking on the 
memory that buffers their messages. Hence, sensitive applications may 
require transmitter and receiver applications to provide end-to-end data 
integrity checking on all LAN messages. 


The Need for CRC Checking 

Cyclic Redundancy Checking (CRC) processing is a powerful error 
checking technique, but is often misunderstood because of its complex- 
ity. Consequently, many popular CRC “implementations” do not imple- 
ment CRC checking to observe existing popular conventions, and so do 
not generally interact correctly outside of limited environments. 

With a message CRC technique, various data fields within a message 
are used to produce a value, called a CRC, which is included as the final 
message field. When a message arrives at its destination, the receiving 
machine uses an identical process to calculate a CRC and compares its 
independently calculated CRC with the one that arrived with the mes- 
sage. If the two CRCs do not match, an error occurred and the communi- 
cation session'proceeds under the protocol’s error recovery provisions. 
However, if the two CRCs do match, chances are “good” that the mes- 
sage arrived without mishap. In truth, using a CRC does not guarantee 
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100% error detection, but it can significantly improve the chances of de- 
tecting errors without the cost of trying to achieve perfect detection. 
How “good” the chances are depends on the CRC method used. Some 
are clearly more effective than others. 


The XMODEM Check Sum 

Ward Christensen’s XMODEM protocol computes a CRC-like value (tech- 
nically a check-sum) for each message by adding together the binary val- 
ues of message characters and dividing the sum by 256. The one-byte 
remainder value is transmitted to, and used by, a receiving machine in 
much the same manner as a CRC . 

Statistical calculations indicate that XMODEM’s approach detects 
about 95% of all potential transmission errors for XMODEM’s 128-byte 
character messages, making its data transmission sessions typically suc- 
cessful. 

As an example of an error that XMODEM does not detect, consider 
one that reverses the position of two adjacent bytes within a message. 
Here, “carp” may erroneously become “crap.” Since the sum of the bi- 
nary values of the characters is the same, the error goes undetected with 
curious and unpredictable social consequences. Because a 5% chance 
for an error to slip through is too large for many applications, CRC tech- 
niques are available to replace XMODEM’s check-sum approach. 


CRC Mathematics 

Protocols that use CRC checking often transmit messages consisting of a 
header field followed by a text field. Within a typical message (Figure 15- 
1), the beginning of the header portion is indicated by an SOH character 
(Start of Header, 0x01). 

The text field begins with an STX character (Start of TeXt, 0x02), 
which also terminates the header field. The text field is terminated by an 
ETX (End of TeXt, 0x03) or ETB (End of Text Block, 0x17). The CRC field 
follows the ETX/B character. The particular message fields used to gener- 
ate the CRC vary by specific protocol and are not addressed here. 

Before discussing how CRC values are computed, let’s review some 
elementary concepts. 
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Fig. 15-1. Format of a typical message. 

Algebraic Polynomial Division 

Recall the many pleasures of polynomial division. In this procedure, 
one algebraic polynomial divides another to yield a quotient polyno- 
mial and a remainder polynomial. For example, suppose you had the 
following: 


F(x) = -F 9x5 + 

P(x) = x2 - 1 

Dividing F(x) by P(x) yields a quotient polynomial Q(x) of 

Q(x) = x5 -F lOx -F 1 
and a remainder R(x) polynomial of 


R(x) = lOx -F 2 


Figure 15-2 has the mathematics for the division. Adding R(x) to the 
product of P(x) by Q(x) returns F(x) as a final result. That is, the process is 
reversible. 

In Figure 15-2, every polynomial has a numeric degree determined 
by the value of the highest power of x found in a term that is nonzero. In 
this example, the degree of P(x) is two; the degree of F(x) is five. When 
one polynomial divides another, the remainder R(x) always has a degree 
less than the degree of the divisor polynomial, P(x). Thus, the remainder 
polynomial always has equal to or fewer terms than the degree of the di- 
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3 2 

X + Ox + 10x + 1 = Q(x) 


2 

X + Ox 


-tI 


5 4 3 2 

X + Ox + 9x + X + Ox + 1 

5 4 3 

X + Ox - X 


Intermediate Remainder- 


4 3 2 

Ox + 10x + X 

4 3 2 

Ox + Ox + Ox 


Intermediate Remainder- 


3 2 

-► 10x + X + Ox 
3 2 

10x + Ox - 10x 


Intermediate Remainder ► x + 10x+ 1 

2 

X + Ox - 1 

Final Remainder ► 10x + 2 = R(x) 

Fig. 15-2. Algebraic polynomial division. 

visor polynomial. In the figure, R(x) has two terms and its degree is one, 
which is less than the degree of P(x). 

The last two terms of F(x) (Ox + 1 ) are not divided by P(x) because 
they have a smaller degree than the divisor. Their presence is reflected in 
the remainder R(x), but not the quotient Q(x). Stated differently, the divi- 
sor polynomial was not directly applied to the low-order terms of F(x). 

All arithmetic in this example uses normal decimal arithmetic within 
standard polynomial division procedures, which produce intermediate 
remainders used in the next step of the division process. 

When subtracting or adding one term from or to another, borrowing 
or carrying from an adjacent term is not permitted because the terms are 
independent. 

Now consider Figure 15-3 which uses a shorthand method to summa- 
rize the steps in this example. 


Modulo IWo Arithmetic and Polynomial Division 

Modulo two arithmetic is easy to confuse with base-two (binary) arith- 
metic because both types allow only digits having a value of zero or one. 
However, in base-two arithmetic, 1 + 1 equals 10 and in modulo two 
arithmetic, 1 + 1 equals zero. 
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1 0 10 1 

1 0 i 0 i" 

1 0 -1 


0 10 1 
0 0 0 


10 1 0 

10 0 -10 

1 10 1 

1 0 -1 


10 2 

Fig. 15-3. Algebraic polynomial division, shorthand form. 


Table 15-1 has the complete addition and subtraction tables for mod- 
ulo two computing, as well a corresponding exclusive-OR table. Clearly, 
there is no difference between the modulo two arithmetic operations 
and the exclusive-OR operation. 


Table 15-1. Modulo Two Arithmetic vs. Exclusive-OR 


First Value 

Second Value 

Sum of Values 

Difference 
of Values 

Exclusive-OR 
of Values 

0 

0 

0 

0 

0 

0 

1 

1 

1 

1 

1 

0 

1 

1 

1 

1 

1 

0 

0 

0 


Thus, if we have two polynomials. 


P(x) = x2 + 1 


F(x) = x^ + x^ + 1 


dividing F(x) by P(x) using modulo two arithmetic yields 


Q(x) = x^ and R(x) = 1 
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See Figure 15-4 for the details. 

3 

X = Q(x) ==1000 

2 _| 5 3 

P(x) = x + 1== 101^101001== F(x) = X + X + 1 

1 0 1 

Intermediate Remainder ► 0 0 0 

0 0 0 

Intermediate Remainder ► 0 0 0 

0 0 0 

Final Remainder ► 0 0 1 == 1 = R(x) 

Fig. 15-4. Modulo two division, shorthand form. 

Adding R(x) to the product of P(x) and Q(x) recovers the original P(x): 
P(x) [X] Q(x) + R(x) = F(x) 

Since modulo two subtraction is equivalent to an exclusive-OR oper- 
ation, 

P(x) [x] Q(x) = F(x) — R(x) = F(x) + R(x) = F(x) exclusive-OR R(x) 

Thus, under modulo two arithmetic rules, dividing a dividend polyno- 
mial F(x) by a polynomial Q(x) produces a remainder polynomial R(x). 
Then, the sum of F(x) and R(x) is evenly divisible by Q(X). Finally, in all 
cases, the coefficients of all polynomial terms is zero or one. 


CRC Calculation 

In CRC calculations, a message’s bit pattern is treated as a shorthand rep- 
resentation of a corresponding polynomial’s coefficients. Assuming 
eight bits per message byte, a given ten-byte message would have 80 bits 
that uniquely define an 80-term polynomial (having terms with degree 
79 through zero). By definition, these polynomial term coefficients all 
have a value of zero or one. 

To compute a message CRC, a selected polynomial (P(x)) divides a 
polynomial (F(x)) derived from the message using the rules of modulo 
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two arithmetic. This yields a remainder polynomial (R(x)) whose coeffi- 
cients have the same shorthand representation as the bits of the mes- 
sage’s CRC value. 


Message Bit Patterns 

Suppose a message consists of three data characters: A, B, and C (Figure 
15-5). To transmit the message, the first byte (A) is transmitted, then the 
second (B), followed by the last (C). However, because the bits of a byte 
are traditionally transmitted low-order bit first, the bits must be reversed 
on a byte-by-byte basis to obtain the corresponding polynomial actually 
representing the message’s bit pattern.* 


"A" Transmitted first "C" Transmitted last 



Message start ► ABC ◄ Message end 

Fig. 15-5. Message byte transmission order. 


Thus, the ASCII character. A, equivalent to a binary 01000001, is 
bitwise reversed to become 10000010. This new value corresponds to 
the polynomial 


IX" + 0X6 + 0X5 + OX'* + 0X5 + 0X2 + ox* + OX® 


CRC Preconditioning 

Once a message’s bit pattern is determined, a number of binary digits 
typically having the same value (all zeros or ones) and equal in number to 
the degree of the polynomial divisor are prepended to the message bit 
pattern (Figure 15-6). This introduces an initial intermediate value re- 
mainder for the subsequent CRC division. 


*One exception to the low-order bit-first transmission rule is the ANSI/IEEE 802.5 
Standard observed by IBM’s Token-Ring adapters. However, since LAN adapters 
traditionally provide CRC checking on the LAN media, all programs in this book 
assume that the low-order bit first convention will be observed. This allows the 
programs to be useful in other telecommunication environments as well as in LAN 
environments. 
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PP . . . PMM. . . MZZ . . . Z 

Legend: P Prepended bit values 
M -► Message bits 
Z “► Appended binary zeros 

Fig. 15-6. Prepending a CRC preconditioning value. 


Binary Zero Padding 

Next, a number of binary zeros, equal in number to the degree of the 
polynomial divisor, are appended to the message bit pattern. This allows 
the divisor polynomial to be applied against every bit position of the 
original message polynomial. 


Modulo Two Division 

The polynomial created by the original message bit pattern and the 
prepending and padding steps is divided using a selected CRC divisor 
polynomial under modulo two arithmetic division rules. 


CRC Postconditioning 

The resulting quotient is discarded and the remainder is subject to fur- 
ther processing under the rules of the CRC generation procedures. Typi- 
cally the value is left alone or is, at most, subject to a bitwise inversion 
where all binary zeros are transformed to binary ones and vice versa. 


CRC Transmission Procedure 

The calculated CRC value is transmitted immediately following transmis- 
sion of the original message. The CRC is transmitted high-order bit first 
as a single unit, even if it consists of more than eight bits. All the CRC bits 
are transmitted, even high-order zero bit(s). 

Transmitting the CRC after the original message characters has the ef- 
fect of subtracting the calculated CRC value from the polynomial created 
by the prepending, message bit reversal, and padding steps (Figure 15-7). 
Prepending CRC bits to the message bit stream has the same effect as sub- 
tracting the CRC value from the message bit stream appended with bi- 
nary zeros. 
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MM . . . MZZ . . . Z 
-CC. ..C 


MM...MCC...C 


Legend; C -►CRC bit values 
M-^ Message bits 
Z-^ Appended binary zeros 

Fig. 15-7. Prepending CRC bits to the message bit stream. 


Message Receipt Procedure 

The receiving machine calculates the CRC on the arriving data characters 
and includes the arriving CRC characters as though they were part of the 
original message. It also omits the CRC postconditioning procedure. 

Processing the original message bytes and the CRC bytes in this man- 
ner results in a value called a residue. Because the receiving machine 
does not perform a CRC postconditioning procedure, the final value is a 
residue and not a CRC. Each CRC implementation expects a specific resi- 
due value for a suceessful message reception. If the calculated residue 
differs from the expected value, an error occurred during the transfer. 


Prevalent CRC Polynomials 


The mathematical theory involved in selecting effective divisor poly- 
nomials for CRC computations is beyond most graduate mathematics 
courses. It involves mathematical field theory at levels that make all but 
the most dedicated math aficionados blanch in bewilderment. Luckily, 
we can present the results of the mathematics without understanding the 
process used to derive them. 

The most commonly used CRC polynomials, their associated pre- 
conditioning values and postconditioning procedures, and receiving sta- 
tion-specific final remainders are indicated in Table 15-2. 

Because the remainder for degree 16 divisor polynomials is degree 15 
or less, using one of the first two polynomials (CRC-16 or CRC-CCITT) 
results in a l6-bit remainder. This allows detection of all errors spanning 
l6 bits or less and about 99.995% of the others. 
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Table 15-2. Popular CRC Values 


Polynomial 

Polynomial 

Name 

Preconditioning Postconditioning 
Value Procedure 

Final 

Residue 

^16 _j_ ^15 + + 1 

CRC-16 

0x0000 

None 

0x0000 


CRC-CCITT 




Xl6 -f. xl2 + x5 H- 1 

(SDLC/HDLC) 

OxFFFF 

Bit Inversion 

OxFOBS 

X32 + x26 + x23 -h 

X22 _j_ xl6 -1- xl2 + 

+ X« + 

x7 + x5-hX'^ + 

x^ -h X + 1 

CRC-32 

OxFFFFFFFF 

Bit Inversion 

0XDEBB20E3 


Which Polynomial Should You Use? 

Statistical analysis shows that the SDLC/HDLC polynomial is slightly bet- 
ter suited to some communication environments. This advantage is pri- 
marily due to the data link layers associated with this polynomial that 
typically use bit-stuffing techniques to guarantee the absence of SDLC/ 
HDLC frame flag bytes within messages. So, if you are not doing bit-stuff- 
ing, the CRC-16 and CRC-CCITT polynomials are virtually equivalent in 
their ability to detect errors. 

For messages less than 4,000 characters, either the CRC-16 or CRC- 
CCITT polynomials are excellent. However, the 99.995% error detec- 
tion rate for the l6-bit CRC polynomials decreases as the message size 
becomes larger than 4,000 bytes. So, if you are sending large messages or 
want an extra measure of data integrity, use the CRC-32 polynomial. 
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The CRCT6 and the CRC-CCITT polynomials have reversed forms. 
The reversed form of CRC-16 is 

xi6 + x'-* + X + 1 

and of CRC-CCITT is the following: 


+ x" -t- x^ + 1 




Chapter 16 


CRC-16 and CRC General Mechanics 


Suppose we wish to compute the CRC-16 CRC for a message consisting of 
the three characters “ABC.” Remembering the bit reversal on a byte-by- 
byte basis, the CRC preconditioning step, and padding of 16 binary zero 
bits forced by division by a polynomial of degree 16, the division is set 
up as illustrated in Figure 16-1. Note that the prepending step can be omit- 
ted for CRC-16 because it only prepends binary zeros. 

"A” = 01000001 -► 100000010 
"B” = 01000010 -► 010000010 
"C" = 01000011 -*• 110000010 


1 10000000 000001 o’iNl 00000000 00000000 100000010 010000010 110000010 00000000 00000000 

^4- CRC-16 divisor —H !◄ 16 zeros H H — A — H 1^ — B — ►! h — C — H 1^^ 16 zeros H 

(preconditioning) Bitwise Bitwise Bitwise (padding) 

Reversed Reversed Reversed 

Fig. 16-1. Sample CRC-16 division setup. 

For those interested in performing the computation, the division re- 
mainder is 0x4521 or binary 0100010100100001. If the result is not obvi- 
ous, don’t worry — it isn’t. Although the task of hand-computing the 
remainder of a 4,000-character message is formidable, the thought is 
completely unnerving! 

A C function that performs the individual bit reversals and related 
computations is illustrated without further comment in Listing 16-1. 
While looking at this program, you might well imagine the computa- 
tional pressure on the engine to produce CRCs with all the bit selection. 
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shifting, and exclusive-ORing involved that occurs for each message 
byte. Moreover, the CRC itself must be reversed bitwise before transmit- 
ting (not illustrated). Surely there must be a better way, and there is. How- 
ever, many programs continue to use the slow, inefficient method 
despite the existence of superior approaches. 


Listing 16-1. Bit-Oriented CRC Calculation 
unsigned CrcAccum; /* keep intermediate remainders here... */ 

WdsCrcCaLc2(NewChar) /* inefficient, traditional CRC-16 routine */ 

unsigned char NewChar; /> this is the next character to compute on */ 

i nt i ; 
long x; 

unsigned char ReversedChar; 

ReversedChar = ReverseChar(NewChar) ; /* reverse the byte's bits */ 

X = ( (long) CrcAccum « 8) + ReversedChar; /* append byte to 

intermediate remainder */ 


for ( i = 0; i < 8; i++) -C 


/* loop here */ 


X «= 1; 


/* stage up the high-order bit */ 


> 


if ( X & 0x01000000 ) 
X 0x01102100; 


/* high-order bit a one? */ 

/* if so, subtract the divisor */ 


CrcAccum = ((( x & OxOOFFFFOO) » 8 )); /* eliminate debris and save */ 

> 


unsigned ReverseChar(c) 
unsigned char c; 

unsigned i, ShiftRight, ShiftLeft; 
unsigned char ReversedC; 

ReversedC = 0; 

ShiftRight = 0x0080; /* beware, below right-shifting isn't portable */ 

ShiftLeft = 0x0001; 

for (i = 0; i < 8; ShiftLeft «= 1, ShiftRight »= 1, i++) { 


*/ 


if( c & ShiftRight) 


/* found a one-bit? 
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Listing l6-l. (cont.) 

ReversedC |= ShiftLeft; /* if so, set it reversed */ 

> 

return(ReversedC) ; 

> 


CRC Hardware 

Because CRC approaches existed before the widespread availability of 
microprocessors, CRC computation was usually accomplished in hard- 
ware. A preliminary representation of hardware circuitry necessary to 
produce CRC-16 CRCs is illustrated in Figure l6-2. Note the bits are or- 
dered differently in the data and intermediate remainder registers. 



c cc ccc cc 

1 2 3 12 13 14 15 16 



Fig. l6-2. Preliminary CRC-16 hardware arrangement. 


At the beginning of each message, the intermediate remainder regis- 
ter is initialized to the appropriate preconditioning value (0x0000 for 
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CRC-16). Each message data byte is sequentially placed in the data regis- 
ter, which shifts from left to right. For each byte, the illustrated circuitry 
emulates the CRC-16 modulo two polynomial division process by using 
the value of the intermediate remainder register’s high-order bit (C[l]) to 
subtract the lower order terms of the divisor polynomial, when appro- 
priate (x* * 15, X* *2, and X* *0), and create new intermediate remainders. 

The subtraction is accomplished by exclusive-OR gates on the inter- 
mediate remainder’s lower order bits. They are moved from right to left 
as the high-order bit rotates out of the intermediate remainder shift regis- 
ter circuitry. 

Each nonzero divisor polynomial term requires an exclusive-OR 
gate, which is situated so that adding the value of the subscript of the bit 
intermediate remainder register immediately to the left of the OR gate to 
the exponent of the corresponding polynomial divisor term produces a 
sum of sixteen. (Here, 1 plus 15, 14 plus 2, and 16 plus 0 all equal 16.) 

If the current intermediate remainder register high-order bit (C[l]) is 
a zero bit, then the lower order bits are promoted untouched and a sub- 
traction of all zero bits results. If the intermediate remainder register 
high-order bit is a one bit, the lower order bits of the divisor polynomial 
are exclusive-ORed at the appropriate positions as the bits are promoted 
to the next bit position. 

Each time the current high-order bit shifts out of the intermediate re- 
mainder register, the current low-order bit in the data register shifts into 
the low-order bit of the intermediate remainder register, perhaps being 
modified by the value of the latter’s high-order bit in the process. This 
emulates the polynomial division process which introduces new bits 
into the current intermediate remainders by having them drop down 
from the dividend. 

When the data register has shifted eight times (assuming eight bits to a 
byte), the next sequential message data byte is placed in the data register. 
When there are no more data bytes to transmit, two bytes of zeros are 
sequentially placed in the data register to achieve the necessary padding 
of binary zeros for a l6th-order CRC divisor polynomial. Since there is 
no postconditioning step, this completes the CRC calculation process 
and the l6-bit CRC value can be transmitted. However, the l6-bit value 
must be transmitted high-order bit first as a contiguous unit (e.g., as bits 
C[l], C[2], . . . , C[l6]). This requires a bit reversal of the CRC value to 
compensate for the transmission circuitry’s transmitting the low-order 
bit first. Rather than do this in hardware, the circuitry can compute the 
entire CRC in a bit-reversed manner. This is illustrated in Figure l6-3 and 
explains why the register bit positions were numbered differently in Fig- 
ure l6-2. 
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|c 


□ Data Register c 


High bitsC 


Shifting direction C 


Low bits 

z=> 



cc cc cccc c 

16 15 14 13 5 4 3 2 1 


Low bits High bits 

~ '""—i intRrmRfliatf! Remainder Registeru ^ 

Shifting direction i : 


Fig. l6-3. Improved CRC-16 hardware arrangement. 


Note, the two final binary zero padding bytes have the effect of multi- 
plying the message polynomial by 2 * * 16, but advancing the introduc- 
tion of the data bits by 16 positions has the same effect. So, using the 
popular circuitry illustrated in Figure l6-4 eliminates the requirement to 
process the final two bytes of binary zeros and accelerates the CRC calcu- 
lation in the process. In this scheme, the right-most bits of both registers 
are exclusive-ORed together to produce an intermediate bit value of ei- 
ther a zero or one. (In the case of the data register, the right-most bit is the 
low-order bit; in the case of the intermediate remainder register, it is actu- 
ally the high-order bit.) The registers are then shifted to the right one bit 
position. 

During the shift, the intermediate bit value is also exclusive-ORed 
with the bits leaving CRC register bit positions 15 and 2. The results of 
these operations are then placed in positions 14 and 1, respectively. In 
addition, the intermediate bit value is placed in the intermediate remain- 
der’s register bit position 16. Finally, the data register is shifted right one 
position to present the next bit for processing. 
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Data Register 




High bitsE 


iJ^Low bits 


I I I I I I h 

DDDDDDDD 
8 7 6 5 4 3 2 1 


t 


1 

2 

X 

r ^ 

+ 

▲ 

15 

X 

r 

^ iu.^m 


cc cc cccc c 

16 15 14 13 5 4 3 2 1 


Low bits : ^ ; .i High bits 

‘ “"l Intprmftrtiatfi Remainder Register I " ^ ^ 


Fig. l6-4. Final CRC-16 hardware arrangement. 


Observations 

All data bits are naturally processed in reverse order on a byte-by-byte 
basis, so bit-reversal provisions are not required in this method. In addi- 
tion, inserting data bits at the new position eliminates processing the two 
bytes of zero padding. Finally, the CRC register is arranged so that it can 
be right-shifted as a unit for proper transmission. This is done by trans- 
mitting the right-most byte first followed by the left-most byte. 

If it seems a bit mysterious, it really isn’t. Let’s shift a byte through a 
CRC-16 generator by hand. The data byte is binary 00000001. 


start : Data = 0000000 1 

I 

I 

V 

+ Intermediate value = 1 

II I A 

I I I 

IV V I 

->00 + 0000000000000 + 0 




Chapter 16: CRC-16 and General Mechanics 


187 


Result after shift 1 Data = XOOOOOO 0 


V 

+ New Intermediate value = 1 

II I A 

I I I 


~>10 + 1000000000000 + 1 


Result after shift 2 


Data = XXOOOOO 0 

I 

I 

V 


->11 + 1100000000000 + 1 


New Intermediate value = 1 


Result after shift 3 


Data = XXXOOOO 0 

I 

I 

V 


->11 


V V 1 

+ 0110000000000 + 1 


New Intermediate value = 1 


Result after shift 4 


Data = XXXXOOO 0 


V 

+ New Intermediate value = 1 


II I A 

I I I 


V V I 

->11 + 0011000000000 + 1 
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Result after shift 5 Data = XXXXXOO 0 


V 


+ New Intermediate value = 1 


->11 + 0001100000000 + 1 


Result after shift 6 Data = XXXXXXO 0 

I 

I 

V 

+ New Intermediate value = 1 

II I A 

I I I 

IV VI 

->11 + 0000110000000 + 1 


Result after shift 7 


Data = XXXXXXX 0 

I 

I 

V 


+ New Intermediate value = 1 


->11 + 0000011000000 + 1 


Result after shift 8 


Data = XXXXXXX 


X Need another data byte 

I 

I 

V 


Final Value 


->11 


V V 

+ 0000001100000 + 1 


+ ??? 


New Intermediate value 

cannot be determined until 
the next data byte is loaded 
into the data register 


When manually computing the CRC for this byte using modulo two 
polynomial division, be sure to perform the necessary bit reversal and bit 
padding of the dividend value. 
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Because CRC-16 has no postconditioning, the CRC-16 value for this 
operation is equal to the value that is left in the intermediate remainder 
register. This value is subsequently transmitted and processed as though 
it were a single value spanning two data bytes. 

If the receiving station has the same CRC value in its CRC register (as 
it is on a successful transmission), it receives the right-most CRC byte 
first. Thus, the intermediate bit value produced by the exclusive-ORing 
process during the receipt of the inbound CRC-16 CRC value is always a 
zero bit. Similarly, the intermediate values produced by processing the 
left-most byte of the CRC-16 CRC value should always yield an intermedi- 
ate bit value of binary zero at each step. Thus, when the receiving station 
completes processing the incoming CRC bytes, there should always be a 
zero value in the receiving station’s intermediate CRC-16 register. 

This is the test for a successful transmission using CRC-16 and corres- 
ponds to our observation that there should be no remainder because 

P(x) [x] Q(x) = F(x) — R(x) = F(x) Exclusive-OR R(x) = F(x) + R(x) 

Here, F(x) is the message polynomial multiplied by X* 16 (padded with 
two bytes of binary zeros). In other words, transmitting the CRC and pro- 
cessing it as part of the inbound message is equivalent to adding it to a 
message that has been right-shifted 16 bits resulting in an evenly divisible 
polynomial. 

The zero residue test does not hold for all CRCs, however. Because 
the CRC-CCITT calculation process has a bit-inverting postconditioning 
step, the remainder is not transmitted — only its inverse. This means the 
inbound data stream is guaranteed not to be evenly divisible and always 
leaves a nonzero residue after processing. This is clear because, during 
receipt of the inbound CRC-CCITT CRC value, the bit inversion step al- 
ways forces the intermediate bit values to have a value of one. 

One small problem remains. The programming to achieve this ap- 
proach is no faster or easier than for the preceding polynomial division dis- 
cussion example. What is needed is an approach that is fast and easy to 
code. 


Generalized CRC-16 Shifting 

Suppose that you want to calculate the CRC-16 of an arbitrary byte for an 
arbitrary value in the intermediate remainder register. Assume the follow- 
ing layout: 
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High Low 

Data Byte: D8 D7 D6 D5 D4 D3 D2 D1 

Low High 

|< Intermediate Remainder Register >l 

C16 C15 C14 C13 C12 C11 C10 C9 C8 C7 C6 C5 C4 C3 C2 C1 


Using the procedure outlined above, we can apply the arbitrary byte to 
the arbitrary CRC value. As before, D1 and Cl are exclusive-ORed to- 
gether. The result is exclusive-ORed to bits C15 and C2 as they shift to the 
left and the result of exclusive-ORing D1 and Cl is placed in Cl6. The 
data byte and intermediate remainder register look like this: 

Data Byte: X D8 D7 D6 D5 D4 D3 02 

|< Intermediate Remainder Register >| 

0 C16 CIS C14 C13 C12 C11 CIO C9 C8 C7 C6 C5 C4 C3 C2 

VI V1 VI 

where V1 = D1 + C1 and all values within a CRC intermediate register 
column are exclusive-ORed together to provide the bit value for that bit 
position within the register. In general, let Vi = Di + Ci. 

After processing two bits, the data byte and intermediate remainder 
register look like this: 

Data Byte: X X 07 D6 D5 D4 03 

]< Intermediate Remainder Register >] 

0 0 C16 C15 C14 C13 C12 C11 C10 C9 C8 C7 C6 C5 C4 C3 

VI VI VI 

V2 V2 V2 

After processing three bits, the data byte and intermediate remainder reg- 
ister look like this: 


Data Byte: X X X 07 06 05 04 

]< Intermediate Remainder Register >| 

0 0 0 C16 CIS C14 C13 C12 C11 CIO C9 C8 C7 C6 C5 C4 
VI VI VI 

V2 V2 V2 

V3 V3 V3 


VI 
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After processing four bits, the data byte and intermediate remainder reg- 
ister look like this: 


Data Byte: X X X X D7 D6 D5 


]< Intermediate Remainder Register >| 


0 0 0 0 C16 CIS CU C13 C12 C11 CIO C9 C8 C7 C6 C5 


VI VI VI 

V2 V2 V2 

V3 V3 V3 

V4 V4 V4 


After processing 8 bits, elimination of canceling instances of the same 
bits involved in a bit position’s exclusive-OR calculation, and rearrange- 
ment of values, the data byte and CRC register look like this: 


Data Byte: XXXXXXXX 


l<- 

— 

— 

— 

Intermediate Remainder Register 

> 

0 

0 

0 

0 

0 

0 

0 

0 

C16 C1S C14 C13 C12 C11 

CIO C9 

V1 

V1 

V7 

V6 

V5 

V4 

V3 

V2 

V1 V1 

V1 

V2 

V2 

V8 

V7 

V6 

V5 

V4 

V3 

V2 

V2 

V3 

V3 








V3 

V4 

V4 








V4 

V5 

V5 








V5 

V6 

V6 








V6 

V7 

V7 








V7 

V8 









V8 


This is equivalent to the following diagram: 

Data Byte: XXXXXXXX 


|< Intermediate Remainder Register >| 

0 0 0 0 0 0 0 0 C16 CIS C14 C13 C12 C11 CIO C9 

VI VI V8 V7 V6 VS V4 V3 V2 VI VI 

V2 V2 V2 

V3 V3 V3 

V4 V4 V4 

VS VS VS 

V6 V6 V6 

V7 V7 V7 

V8 V8 V8 

V8 V7 V6 VS V4 V3 V2 VI 
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Noting that P = VI + V2 + V3 + V4 + V5 + V6 + V7 +V8 is simply the 
parity of the data byte (even or odd), the figure collapses to 

Data Byte: XXXXXXXX 

|< Intermediate Remainder Register >| 

0 0 0 0 0 0 0 0 C16 C15 C14 C13 C12 C11 C10 C9 

V8 V7 V6 V5 V4 V3 V2 V1 

V8 V7 V6 V5 V4 V3 V2 V1 

P P P 

which provides an ultrahigh-performance CRC-16 computation ap- 
proach for assembly language programs on machines providing parity 
values for data characters. 


Table Look-Up Schemes 

These diagrams all indicate that the new intermediate remainder of a CRC- 
16 calculation is computable from the initial values of the data byte and the 
intermediate remainder register. Specifically, if you create an intermediate 
byte value V that is the exclusive-OR of the left-most byte of the existing 
CRC intermediate remainder and the new data byte, the new CRC interme- 
diate remainder is created by right-shifting by eight bits (with zero filling in 
the high-order positions) the existing CRC intermediate remainder, and 
exclusive-ORing a value that can be derived from the various bits of V. 
Since V can only have 256 values, it is possible to construct a table that 
holds the 256 unsigned integer values. Then, the value corresponding to a 
particular value of V is quickly located, using V as an index. 

The CRC-16 calculation algorithm now becomes: 

1 . At the beginning of each message, set the intermediate remainder 
register to zero (the CRC-16 preconditioning step). 

2. Fetch the first byte of the message. 

3- Exclusive-OR the fetched byte with the low-order byte of the in- 
termediate remainder to obtain a byte V. 

4. Right-shift the intermediate remainder eight bits with the high-or- 
der bits (being zero) filling in the process. 

5. Using V as an index, fetch a l6-bit unsigned integer value from the 
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CRC table and exclusive-OR it to the shifted intermediate remain- 
der. 

6. The result of the exclusive-OR operation is the new value of the 
intermediate remainder. 

7. For each unprocessed byte in the message, sequentially fetch the 
byte and go to step 3. 

8. The intermediate remainder is transmitted left -most byte first, fol- 
lowed by the right-most byte. 

This approach processes entire bytes of data using a look-up table. Hence 
the popular name Bytewise Table Look-up CRC. 

The C program in Listing l6-2 computes the CRC-16 look-up table and 
shows how to use it. The first CRC-16 computation is on the binary value 
0x0100 which produces a bitwise- reversed CRC value of 0x9001. The sec- 
ond example calculates the CRC-16 of 0x0100 followed by its bytewise-re- 
versed CRC (0x0190). In this case, the CRC is zero as it should be. 

The third example illustrates that a string’s CRC calculation should 
not include the terminating NULL character. In general, the C function 
strlen cannot be used to compute the length of a message because the 
message may contain NULL characters, which cause the strlen function 
to return an incorrect (shorter) message length. 

Listing 16-2. CRC16.C 


/* */ 

/* High Performance CRC-16 Computation Routine */ 
/★ */ 
/* Copyright 1988 W. David Schwaderer */ 
/* All rights reserved */ 
/* ★/ 
/* Warning.', .thi s program uses bit fields! */ 
/* For warnings on bit field hazards see: */ 
/* */ 
/* C Wizard's Programming Reference */ 
/* W. David Schwaderer */ 
/* , Wiley Press, 1985 */ 
/★ ★/ 
/* */ 


#define LINT^ARGS 

//include <stdio.h> 
//include "netbiosZ.h" 
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Listing l6-2. (cont.) 


#if defined(LINT_ARGS) 
extern int mainCint argc,char * *argv); 
extern void GenerateTabLe(void) ; 
extern void PrintTabLe(void); 

extern unsigned int GenerateCRCCunsigned int Length, char *TextPtr); 
extern void Logo(void); 

#endi f 

USGI crc_tabLeC256] ; /* gLobaUy accessible */ 

mainCargc, argv) 
int argc; 
char *argv[] ; 

USGI length, crc; 


/* crc = 0x9001 */ 
static char TestArrayH] = { '\x01', *\x00'>; 

static char TestArray2[] = { *\x01*, *\x00', '\x01', '\x90'>; 

/* bytewise bytewise */ 

/* unreversed reversed */ 


static char TestMsgC] = "This is a test message."; 
LogoO ; 


GenerateTableO ; 

/* compute the 

crc__table 

*/ 


PrintTableO ; 

/* display the 

table 

*/ 


length = si zeof (TestArrayD ; 

/* example 1 



*/ 

crc = GenerateCRCClength, 

TestArrayD; /* calculate CRC 


*/ 

printf C"\n\n\nTestArray1 CRC 

= 0x%04X", crc); 




length = sizeof CTestArray2) ; 

/* example 2 


*/ 



crc = GenerateCRCClength, TestArray2); /* calculate CRC */ 
printf ("\n\n\nTestArray2 CRC = 0x%04X", crc); 

/* example 3 */ 
length = si zeof (TestMsg) - 1; /* avoid terminating NUL */ 
crc = GenerateCRCClength, TestMsg); /* calculate a CRC */ 
printf ("\n\n\nText = C%s]\nCRC = %04X\n\n", TestMsg, crc); 
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Listing l6-2. (cont.) 

return 0; 



> 



void GenerateTableO /* generate the look-up table */ 




int temp; 



union i int i; 



struct { 



USGI i1 

1 

/★ low order bit */ 

USGI i2 

1 


USGI i3 

1 


USGI i4 

1 


USGI 15 

1 


USGI i6 

1 


USGI 17 

1 


USGI 18 

1 

/* high order bit */ 

USGI 

8 

/* unused byte */ 

> Bit; 



> iUn; 



union -C USGI Entry; 



struct { 



USGI b1 

1 

/* low order bit */ 

USGI b2 

1 


USGI b3 

1 


USGI b4 

1 


USGI b5 

1 


USGI b6 

1 


USGI b7 

1 


USGI b8 

1 


USGI b9 

1 


USGI bio 

1 


USGI b11 

1 


USGI b12 

1 


USGI b13 

1 


USGI b14 

1 


USGI b15 

1 


USGI b16 

1 

/* high order bit */ 

> EntryBIt; 



} EntryUn; 



for (iUn.1 = 0; IUn.1 < 256; 

iUn.i++) { 

EntryUn. Entry = 0; /* bits 

2 

thru 6 zeroed out now */ 
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Listing 16-2. (cont.) 


temp = (iUn.Bit.i7 iUn.Bit.i6 iUn.Bit.i5 

iUn.Bit.i4 iUn.Bit.i3 ^ iUn.Bit.i2 

iUn.Bit.i1); 


Ent ryUn . Ent ryB i t . b1 6 
EntryUn.EntryBi t .b15 
EntryUn.EntryBi t .b14 
EntryUn.EntryBi t .b13 
EntryUn.EntryBi t.b1 2 
Ent ryUn . Ent ryBi t . b11 
EntryUn.EntryBi t .bio 
EntryUn.EntryBit.b9 
EntryUn. Ent ryBi t.bS 
EntryUn.EntryBi t.b7 
EntryUn.EntryBi t .b1 


(iUn.Bit.i8 
(temp) ; 
(iUn.Bit.i8 
(iUn.Bit.i7 
(iUn.Bit.i6 ^ 
(iUn.Bit.i5 ^ 
(iUn.Bit.i4 
(iUn.Bit.i3 ^ 
(iUn.Bit.i2 ^ 
(iUn.Bit.i1); 
(iUn.Bit.i8 ^ 


temp) ; 

iUn.Bit .i7); 
iUn.Bit .i6) ; 
iUn.Bit.i5) ; 
iUn.Bit.i4); 
iUn.Bit. i 3); 
iUn.Bi t . i2) ; 
i Un . B i t . i 1 ) ; 

temp) ; 


crc__tabLe[iUn. i ] = EntryUn. Entry; 


> 


} 

void PrintTableO /* print out the Look-up table */ 

int i ; 

for (i = 0; i < 256; i++) -C 
if ( ! (i % 8) ) 

printfC'Xn 0x%02X - %04X'', i, crc__tabLe[i ]) ; 
else 

printfC %04X'', crc_table[i ]) ; 

> 

> 

USGI GenerateCRCdength, TextPtr) 

USGI Length; 
char *TextPtr; 

int i, index; 

USGI crc; 


crc = 0; 


/* crc starts at zero for each message */ 



Chapter 16: CRC-16 and General Mechanics 


197 


Listing l6-2. (cont.) 

for (i = 0; i < Length; i++, TextPtr++) { 
index = ( (crc *TextPtr) & OxOOFF); 
crc = ( (crc » 8) & OxOOFF) crc_tabLeCindex] ; 

> 


return crc; 


> 


void LogoO 

printf("\n\n High Performance CRC-16 Computation Routine"); 
printf("\n Copyright 1988 W. David Schwaderer\n\n") ; 

> 

/* * Program Output * 


0x00 

- 

0000 

C0C1 

C181 

0140 

C301 

03C0 

0280 

C241 

0x08 

- 

C601 

06C0 

0780 

C741 

0500 

C5C1 

C481 

0440 

0x10 

- 

CC01 

occo 

0D80 

CD41 

OFOO 

CFC1 

CE81 

0E40 

0x18 

- 

OAOO 

CAC1 

CB81 

0B40 

C901 

09C0 

0880 

C841 

0x20 

- 

D801 

18C0 

1980 

D941 

1B00 

DBC1 

DA81 

1A40 

0x28 

- 

1E00 

DEC1 

DF81 

1F40 

DD01 

1DC0 

1C80 

DC41 

0x30 

- 

1400 

D4C1 

D581 

1540 

D701 

17C0 

1680 

D641 

0x38 

- 

D201 

12C0 

1380 

D341 

1100 

D1C1 

D081 

1040 

0x40 

- 

F001 

30C0 

3180 

FI 41 

3300 

F3C1 

F281 

3240 

0x48 

- 

3600 

F6C1 

F781 

3740 

F501 

35C0 

3480 

F441 

0x50 

- 

3C00 

FCC1 

FD81 

3D40 

FF01 

3FC0 

3E80 

FE41 

0x58 

- 

FA01 

3AC0 

3B80 

FB41 

3900 

F9C1 

F881 

3840 

0x60 

- 

2800 

E8C1 

E981 

2940 

EB01 

2BC0 

2A80 

EA41 

0x68 

- 

EE01 

2EC0 

2F80 

EF41 

2D00 

EDC1 

EC81 

2C40 

0x70 

- 

E401 

24C0 

2580 

E541 

2700 

E7C1 

E681 

2640 

0x78 

- 

2200 

E2C1 

E381 

2340 

El 01 

21 CO 

2080 

E041 

0x80 

- 

A001 

60C0 

6180 

A141 

6300 

A3C1 

A281 

6240 

0x88 

- 

6600 

A6C1 

A781 

6740 

A501 

65 CO 

6480 

A441 

0x90 

- 

6C00 

ACC1 

AD81 

6D40 

AF01 

6FC0 

6E80 

AE41 

0x98 

- 

AA01 

6AC0 

6B80 

AB41 

6900 

A9C1 

A881 

6840 

OxAO 

- 

7800 

B8C1 

B981 

7940 

BB01 

7BC0 

7A80 

BA41 

0xA8 

- 

BE01 

7EC0 

7F80 

BF41 

7D00 

BDC1 

BC81 

7C40 

OxBO 

- 

B401 

74C0 

7580 

B541 

7700 

B7C1 

B681 

7640 

0xB8 

- 

7200 

B2C1 

B381 

7340 

B101 

71 CO 

7080 

B041 

OxCO 

- 

5000 

90C1 

9181 

5140 

9301 

53 CO 

5280 

9241 

0xC8 

- 

9601 

56C0 

5780 

9741 

5500 

95C1 

9481 

5440 

OxDO 

- 

9C01 

5CC0 

5D80 

9D41 

5F00 

9FC1 

9E81 

5E40 
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Listing l6-2. 

(cont.) 


0xD8 

- 5A00 

9AC1 

9B81 

5840 

9901 

59C0 

5880 

9841 

OxEO 

> 8801 

48C0 

4980 

8941 

4800 

88C1 

8A81 

4A40 

0xE8 

“ 4E00 

8EC1 

8F81 

4F40 

8D01 

4DC0 

4C80 

8C41 

OxFO 

- 4400 

84C1 

8581 

4540 

8701 

47C0 

4680 

8641 

0xF8 

“ 8201 

42C0 

4380 

8341 

4100 

81 Cl 

8081 

4040 


TestArrayl CRC = 0x9001 

TestArray2 CRC = 0x0000 


Text = [This is a test message.] 
CRC = 9D6A 

*/ 


CRC Compatibility Caveats 

A number of “CRC implementations” exist that do not provide the re- 
sults the example CRC programs in this book provide. Typically, the dif- 
ferences in the other implementations are a consequence of their 
ignoring one or more of the following conventions: 

• the bit reversal legacy of message characters 

• the convention of transmitting a CRC in a contiguous bit-reversed 
manner, high-order bit first 

• international preconditioning and postconditioning standards for 
different CRC computation approaches 

The CRC example programs in this book operate correctly in a variety 
of hardware and software environments. Ignoring data communication 
legacies, arcane as they may be, precludes the other “CRC implementa- 
tions” from successfully operating in the same environments, though the 
other implementations can operate with each other when each ignores 
the identical conventions. 

Each of the CRC programs in this section builds a table and then uses 
it. Clearly a more efficient approach is to define the table as an array of 
constants so that it does not have to be generated each time the program 
executes. 
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CRC-CCITT and Minimum Look-Up 
l^ble Sizes 


The CRC-CCITT polynomial is: 

xi6 + x'2 + x’ + 1 

Using the discussion in Chapter 16 as a reference, the appropriate CRC- 
CCITT generation hardware is illustrated in Figure 17-1. 


r^r- 


□ Data Register 




High bitsC 


Low bits 


DDDDDDDD 
8 7 6 5 4 3 2 1 


-F 


0 

X 

5 

X 

r ^ 

A 

12 

X 

r 

* _u-.n..ru_ □- 


ccccc c c cccc 

16 15 14 13 12 11 5 4 3 2 1 


CCCCC C C CCCC 

16 15 14 13 12 11 5 4 3 2 1 

Low bits High bits 

' Intermediate Remainder Register t : — [ ]>| 

Shifting direction r...:::.'":. .a- ? ■ 


Fig. 17-1. Typical CRC-CCITT hardware representation. 
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After processing 1 bit, the intermediate remainder register value is: 

0 C16 C15 C14 C13 C12 C11 CIO C09 COS C07 C06 COS C04 C03 C02 

V01 V01 V01 

After processing 2 bits, the intermediate remainder register value is: 

0 0 C16 CIS C14 C13 C12 C11 C10 C09 COS C07 C06 COS C04 C03 

V02 V01 V02 V01 V02 V01 

After processing 3 bits, the intermediate remainder register value is: 

0 0 0 C16 CIS C14 C13 C12 C11 C10 C09 COS C07 C06 COS C04 

V03 V02 V01 V03 V02 V01 V03 V02 V01 

After processing 4 bits, the intermediate remainder register value is: 

0 0 0 0 C16 CIS C14 C13 C12 C11 CIO C09 COS C07 C06 COS 

V04 V03 V02 V01 V04 V03 V02 V01 V04 V03 V02 V01 

After processing 8 bits, the intermediate remainder register value is: 

0 0 0 0 0 0 0 0 C16 CIS C14 C13 C12 C11 CIO C09 

VOS V07 V06 VOS V04 V03 V02 V01 V04 V03 V02 V01 

V04 V03 V02 V01 VOS V07 V06 VOS VOS V07 V06 VOS 

V04 V03 V02 V01 V04 V03 V02 V01 


The Tible Look-Up Approach 

If a C program uses a CRC-CCITT bytewise table look-up approach, the 
table requires an array of 256 unsigned integers occupying 512 bytes of 
memory for a typical machine. Thus, there would be no space savings. 
However, a program processes each byte’s nibbles independently, just as 
it processes each message byte independently. Reexamining the CRC- 
CCITT intermediate register after processing four bits indicates this is 
very easy to do. 

This approach only requires 16 unsigned integers that occupy a mere 
32 bytes in a typical machine. The only requirement is that two table 
look-ups are required for each byte instead of one table look-up. Clearly 
this is a classic trade-off between storage conservation versus conserva- 
tion of machine cycles. 
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A program can also process two bits at a time, requiring four table 
look-ups using a table having four entries and requiring a total of 8 bytes. 
However, the program instructions to achieve the four passes for each 
byte may take more memory than the 24 bytes saved by using a four-en- 
try table instead of a larger l6-entry table. 

The program in Listing 17-1 uses a nibblewise table look-up approach 
to compute CRC-CCITT values. Its structure is similar to the CRC-16 sam- 
ple program, so it is presented without much discussion. The primary 
differences are: 

• It illustrates the compact table-generation principles. 

• It illustrates the proper CRC-CCITT postconditioning step. 

• It illustrates the proper CRC-CCITT preconditioning step. 

• It demonstrates that the CRC-CCITT residue, computed by pro- 
cessing a message and its CRC-CCITT bytes, has a value of 
OxFOBS. 

The only catch is that the program’s GenerateCRC( ) routine always in- 
verts its computed values before returning them. That is not appropriate 
when computing a CRC residue, so there is a nonintuitive value inver- 
sion to undo the unwanted inversion performed by the CRC calculation 
routine. 


Listing 17-1. CRC-CCITT 


/* */ 

/* High Performance Compact */ 
/* CRC-CCITT Computation Routine */ 
/★ ★/ 
/* Copyright 1988 W. David Schwaderer */ 
/* AIL rights reserved */ 
/* */ 
/* Warning. . .this program uses bit fields! */ 
/* For warnings on bit field hazards see: */ 
/* */ 
/* C Wizard's Programming Reference */ 
/* W. David Schwaderer */ 
/* Wiley Press, 1985 */ 
/* */ 
/* 


^define LINT_ARGS 


/^include <stdio.h> 
^include "netbiosZ.h' 
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Listing 17-1. (cont.) 


#if defined(LINT_AR6S) 
extern int mainCint argc,char * *argv); 
extern void GenerateTable(void) ; 
extern void PrintTable(void) ; 

extern unsigned int GenerateCRCCunsigned int Length, 

unsigned char *TextPtr); 

extern void Logo (void); 

#endi f 


USGI crc_tabLe[16]; /* what a tiny table! */ 


char TestArrayl C] = -C ' 

'X', 'Y*, *Z' 

>; /* crc = 

0x7ADD */ 

char TestArray2[] = { ' 

'X', 'Y', 'Z* 

, *\xDD', '\x7A*>; 

/* 

bytewi se 

bytewi se 

*/ 

/* 

unreversed 

reversed 

*/ 


mainCargc, argv) 
int argc; 
char *argv[]; 

{ 

USGI Length, crc, residue; 

LogoO ; 

compute the crc_tabLe */ 

/* display the table */ 

/* example 1 */ 

/* calculate CRC */ 
/* display the CRC */ 

/* example 2 */ 

/* calculate residue */ 

the returned "crc"! — */ 
/* The residue must always be OxFOBS for CRC-CCITT... */ 

printf ("\n\nTestArray2 residue = 0x%04X\n'', "-residue); /* invert! */ 

return 0; 

> 

void GenerateTableO /* generate the Look-up table */ 


GenerateTableO; /* 

PrintTableO ; 

length = si zeof (TestArrayD ; 

crc = GenerateCRCClength, TestArrayD; 

printf ("\n\nTestArray1 CRC = 0x%04X", crc); 

length = si zeof (TestArray2) ; 

residue = GenerateCRCClength, TestArray2); 

/* — To display the residue you must invert 
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Listing 17-1. (cont.) 


USGI temp; 
union -C USGI i ; 

struct -C 


> Bit; 
> iUn; 


USGI i1 

1 

/* 

USGI 12 

1 


USGI 13 

1 


USGI 14 

1 


USGI 15 

1 


USGI 16 

1 


USGI 17 

1 


USGI 18 

1 

/* 

USGI 

8 

/* 


low order bit */ 


high order bit */ 
unused byte */ 


union { USGI Entry; 
struct { 

USGI b1 :1 
USGI b2 
USGI b3 :1 
USGI b4 :1 
USGI b5 :1 
USGI b6 :1 
USGI b7 :1 
USGI b8 :1 
USGI b9 :1 
USGI b10 :1 
USGI b11 :1 
USGI b12 :1 
USGI b13 :1 
USGI b14 :1 
USGI b15 :1 
USGI b16 :1 
> EntryBit; 

> EntryUn; 


/* low order bit */ 


/* high order bit */ 


for (iUn.i = 0; iUn.i < 16; iUn.i++) { /* only 16 entries! */ 

EntryUn. Entry = 0; /* zeros out unreferenced bits */ 

EntryUn.EntryBit.b1 6 = 

EntryUn.EntryBit.b11 = 

EntryUn.EntryBi t .b4 = iUn.Bit.i4; 


EntryUn. EntryBit .b15 = 
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Listing 17-1. (cont.) 

EntryUn.EntryBit.b10 = 

EntryUn.EntryBit .b3 = iUn.Bit.i3; 

EntryUn.EntryBit.b14 = 

EntryUn.EntryBit .b9 = 

EntryUn.EntryBit .b2 = iUn.Bit.i2; 

EntryUn.EntryBit .b13 = 

EntryUn.EntryBit .b8 = 

EntryUn.EntryBit.b1 = iUn.Bit.i1; 

crc_table[iUn.i ] = EntryUn. Entry; /* save the computed value */ 

> 

> 

void PrintTableO /* print out the look-up table */ 

USGI i; 

printf("\n\n Look at this Tiny CRC-CCITT Look-Up Table. .. \n'') ; 

for (i =0; i <16; i++) -C 
if ( !(i % 8) ) 

printf(''\n 0x%02X - %04X”, i, crc_tableCi ]) ; 
else 

printfC %04X", crc_table[i ]) ; 

> 

> 

USGI GenerateCRCCLength, TextPtr) 

USGI Length; 

USGC *TextPtr; 

USGC TempChar; 

USGI i, index, CrcTemp; 

CrcTemp = OxFFFF; /* CRC-CCITT preconditioning ==> OxFFFF */ 

for (i = 0; i < Length; i++, TextPtr++) { 

TempChar = *TextPtr; 

index = ((CrcTemp ^ TempChar) & OxOOOF); /* isolate low-order nibble */ 
CrcTemp = ((CrcTemp » 4) & OxOFFF) crc^tableCindex] ; /* apply it */ 


TempChar »= 4; 


/* stage the next four bits */ 
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Listing 17-1. (cont.) 


index = ((CrcTemp ^ TempChar) & OxOOOF); /* isolate Low-order nibble */ 
CrcTemp = ((CrcTemp » 4) & OxOFFF) crc_tabLeCindex] ; /* 2nd nibble */ 

> 

return -CrcTemp; /* CRC-CCITT post conditioning ==> bit inversion */ 

> 


void LogoO 
{ 

printf("\n\n High Performance Compact"); 

printf("\n CRC-CCITT Computation Routine"); 

printf("\n Copyright 1988 W. David Schwaderer") ; 

> 

/★ End of Program Logic 


/* 


16 12 5 

polynomial =x+x +x+1 
After 4-bit processing cycles... 

b16 b15 b14 b13 b12 b11 blO b9 b8 b7 b6 b5 b4 b3 b2 b1 

0 0 0 0 C16 C15 C14 C13 C12 C11 CIO C09 C08 C07 C06 COS 

V04 V03 V02 V01 - V04 V03 V02 V01 - - - V04 V03 V02 V01 


Each 4-bit processing phase is independent of any other... 

* Program Output * 

Look at this Tiny CRC-CCITT Look-Up Table... 

0x00 - 0000 1081 2102 3183 4204 5285 6306 7387 

0x08 - 8408 9489 A50A B58B C60C D68D E70E F78F 

TestArrayl CRC = 0x7ADD 


TestArray2 residue = 0xF0B8 
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CRC-32 — ^Ibken-Ring, PC Network, 
and Ethernet 


The CRC-32 polynomial is the CRC divisor in IBM Token-Ring, IBM PC 
Network and a variety of other CSMA/CD LANs including Ethernet. Un- 
like the SDLC/HDLC polynomial, CRC-32 provides a 32-bit CRC value 
that is useful to the receipt of messages that are too large for the SDLC/ 
HDLC CRC, though it uses a similar preconditioning and postcondition- 
ing process. 

The CRC-32 preconditioning process loads the intermediate remain- 
der register with OxFFFFFFFF. The postconditioning process inverts the 
final remainder to produce the 32-bit CRC which is transmitted high-or- 
der bit first as a contiguous 3 2 -bit sequence. The appropriate CRC-32 re- 
sidual value is 0xDEBB20E3L. 

Using this discussion as a backdrop, the derivation of a CRC-32 gen- 
eration program is essentially trivial. The following diagrams should be 
obvious at this point in the book: 


DOS D07 D06 DOS D04 D03 D02 D01 --> 
1 

Initial State Before Shifting 1 

1 

V 

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 A 

1 I I I I I I I I I I II I I 

I I I I I I I I I I I II I I 

VVVVVVVVVV V VV V 1 

C32 C31 C30 C29 C28 C27 C26 C25 C24 C23 C22 C21 C20 C19 C18 C17 C16 C15 C14 C13 C12 C11 CIO C09 COS C07 C06 COS C04 C03 C02 C01— > 
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After Shift 1 X DOS D07 D06 DOS D04 D03 D02 


0 

C32 

C31 

C30 

C29 

C28 

C27 

C26 

C25 

C24 

C23 

C22 

C21 

C20 

C19 C18 C17 

C16 C15 C14 

C13 C12 C11 

C10 

C09 

cos 

C07 

C06 

COS 

C04 

C03 

C02 

V01 

V01 

V01 


V01 

V01 


V01 

V01 


V01 

V01 

V01 


V01 


V01 

V01 



V01 




















After Shift 

2 



X 

X 

DOS 

D07 

D06 

DOS 

D04 

D03 

0 

0 

C32 

C31 

C30 

C29 

C28 

C27 

C26 

C25 

C24 

C23 

C22 

C21 

C20 C19 C18 

C17 C16 CIS 

C14 C13 C12 

C11 

C10 

C09 

COS 

C07 

C06 

COS 

C04 

C03 


V01 

V01 

V01 


V01 

V01 


V01 

V01 


V01 

V01 

V01 


V01 


V01 

V01 



V01 





V02 

V02 

V02 


V02 

V02 


V02 

V02 


V02 

V02 

V02 


V02 


V02 

V02 



V02 





















After Shift 

3 




X 

X 

X 

DOS 

D07 

D06 

DOS 

D04 

0 

0 

0 

C32 

C31 

C30 

C29 

C28 

C27 

C26 

C2S 

C24 

C23 

C22 

C21 

C20 Cl 9 

CIS 

C17 C16 CIS C14 C13 

C12 

C11 

CIO 

C09 

COS 

C07 

C06 

COS 

C04 



V01 

V01 

V01 


V01 

V01 


V01 

V01 


V01 

V01 

V01 



V01 



V01 

V01 



V01 





V02 

V02 

V02 


V02 

V02 


V02 

V02 


V02 

V02 

V02 



V02 



V02 

V02 



V02 





V03 

V03 

V03 


V03 

V03 


V03 

V03 


V03 

V03 

V03 



V03 



V03 

V03 



V03 




















After Shift 

4 




X X 

X 

X DOS 

D07 

D06 

DOS 

0 

0 

0 

0 

C32 

C31 

C30 

C29 

C28 

C27 

C26 

C2S 

C24 

C23 C22 C21 

C20 

C19 CIS 

C17 

C16 CIS 

Cl 4 

C13 C12 C11 

CIO 

C09 COS 

C07 

C06 

COS 




V01 

V01 

V01 


V01 

V01 


V01 

V01 


V01 V01 V01 



V01 



V01 

V01 


V01 





V02 

V02 

V02 


V02 

V02 


V02 

V02 


V02 

V02 V02 


V02 




V02 V02 


V02 





V03 V03 V03 

V03 V03 

V03 V03 

V03 V03 V03 


V03 




V03 V03 


V03 




V04 

V04 

V04 


V04 

V04 


V04 

V04 


V04 

V04 

V04 


V04 




V04 

V04 

V04 















After Shift 8 (Final Shift) 

X 

XXX 

X X 

X 

X 

0 0 0 0 

0 

0 

0 

0 

C32 

C31 

C30 

C29 

C28 C27 C26 

C2S 

C24 C23 C22 C21 

C20 C19 CIS C17 C16 CIS C14 C13 

C12 C11 

C10 C09 





V01 

V01 

V01 


V01 

V01 V01 

V01 

V01 V01 V01 

V01 


V01 

V01 





V02 

V02 

V02 


V02 

V02 

V02 V02 


V02 V02 V02 

V02 


V02 V02 





V03 

V03 

V03 


V03 

V03 


V03 V03 

V03 

V03 V03 

V03 

V03 V03 


V03 


V04 

V04 

V04 


V04 

V04 


V04 

V04 V04 

V04 

V04 

V04 

V04 V04 


V04 


VOS 

VOS 

VOS 


VOS 

VOS 


VOS 

VOS 

VOS VOS 

VOS 

VOS 


VOS VOS 

VOS 



V06 V06 

V06 


V06 

V06 


V06 

V06 


V06 V06 V06 


V06 

V06 V06 

V06 



V07 V07 V07 


V07 

V07 


V07 

V07 


V07 

V07 V07 


V07 

V07 V07 

V07 




VOS VOS VOS 

VOS 

VOS 


VOS 

VOS 


VOS 

VOS 

VOS 


VOS 

VOS VOS 

VOS 




V01 V01 V01 


V01 

V01 


V01 

V01 


V01 

V01 V01 


V01 

V01 V01 

V01 




V02 V02 V02 

V02 

V02 


V02 

V02 


V02 

V02 

V02 


V02 

V02 V02 

V02 





The program in Listing 18-1 illustrates a bytewise table look-up to 
generate CRC-32 values. Note that the look-up table occupies 1,024 bytes 
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of memory in a typical machine (256 entries, each requiring four bytes), 
and a nibblewise look-up approach only requires a 64-byte table (l6 en- 
tries, each requiring four bytes). Clearly, a nibblewise table look-up ap- 
proach can provide a substantial advantage in many environments. The 
creation of a nibblewise look-up table approach is left as a trivial exercise 
for the reader. 


Listing 18-1. CRC32.C 


/* */ 

/* High Performance CRC-32 Computation Routine */ 
/★ ★/ 
/* Copyright 1988 W. David Schwaderer */ 
/* ALL rights reserved */ 
/* */ 
/* Warning. . .thi s program uses bit fieLds! */ 
/* For warnings on bit fieLd hazards see: */ 
/★ ★/ 
/* The C Wizard's Programming Reference */ 
/* W. David Schwaderer */ 
/* Wi Ley Press, 1985 */ 
/* */ 
/* */ 


#incLude <stdio.h> 

#incLude "netbiosZ.h" 

^define G00D_CRC32_RESIDUAL 0xDEBB20E3L 

#define LINT_ARGS 

#if defined(LINT_ARGS) 

extern int mainCint argc,char * *argv); 

extern unsigned Long GenerateCRC32(unsigned int Length, char ★TextPtr); 
extern void GenerateTabLe(void) ; 
extern void PrintTabLe(void) ; 
extern void Logo (void); 

#endi f 


USGC 

TestArrayl Cl 

= {'T' 

1 1 a 1 1 c > 

, c , b , 

't'>; /* Crc == 0x78.4D.D1 

.32 */ 

USGC 

TestArray2[] 

= {'T' 

1 fpl Iql 

't ' , 0x32, OxDl , 0x4D, 

0x78>; 



/★ 

byte-wi se 

byte-wise 

*/ 



/* 

unreversed 

reversed 

*/ 



/* 

message 

msg Crc 

*/ 
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Listing 18-1. (cont.) 

char TestMsgC] = "This is a test message."; 

USGL CrcTabLe[256]; /* globally accessible */ 

/★ ====================================== ★/ 

int mainCargc, argv) 
int argc; 
char *argv[] ; 

USGL Crc; 

USGI i, Length; 

LogoO; 

GenerateTableO ; /* fill in the CrcTable */ 

PrintTableO ; /* display the table */ 

Length = sizeof (TestArrayD; /* can't generally use strlen */ 

Crc = GenerateCRC32(Length, TestArrayD; /* calculate CRC-32 */ 

printf ("\n\nTestArray1 CRC == 0x%08lX", Crc); 

Length = sizeof (TestArray2) ; 

Crc = GenerateCRC32(Length, TestArray2); /* calculate CRC-32 */ 

Crc = "Crc; /* we want the actual CRC residue, not its complement */ 

printf ("\n\nReversed CRC32 of TestArray1+i ts CRC == 0x%08lX", Crc); 

if (Crc == G00D_CRC32^RESIDUAL) 

printf ("\n\nThe CRC-32 Calculation is correct..."); 
else 

printf ("\n\nThe CRC-32 Calculation is NOT correct..."); 

printf ("\n\n(TestArray1 -»■ its CRC) Residual as Un-reversed Binary:\n==> "); 

for (i =0; i <32; i++) -C 

if ((i > 0) && <!(i % 8))) 
printf (" ") ; 

else if ((i > 0) && (!(i % 4))) 
printfC"-"); 


if ( ((long) 0x01 « i) & Crc) 
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Listing 18-1. (cont.) 


printf ("1") ; 
else 

printf ("0") ; 

> 

printf (" <==\n"); 

Length = si zeof (TestMsg) - 1; /* avoid terminating NUL */ 
Crc = 6enerateCRC32(Length, TestMsg); /* caLcuLate a CRC */ 
printf ("\n\n\nText = [%s]\nCRC = %08LX\n\n”, TestMsg, Crc); 

return 0; /* end now */ 


> 


/* 


*/ 


USGL GenerateCRC32(Length, TextPtr) 

USGI Length; 
char *TextPtr; 

int i, index; 

USGL Crc; 

Crc = OxFFFFFFFFL; /* CRC starts as all Fs for each message */ 

for (i = 0; i < Length; i++, TextPtr++) { 
index = ( (Crc *TextPtr) & OxOOOOOOFFL) ; 

Crc = ((Crc » 8) & OxOOFFFFFFL) CrcTabLeCindex] ; 


return "Crc; /* return a 1*s complement */ 

> 


/* 


*/ 


void GenerateTableO /* generate the Look-up table */ 

union { USGI i; 

struct { 

USGI i1 :1; /★ MSC low order bit ★/ 

USGI i2 :1; 

USGI i3 :1; 

USGI i4 :1; 
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Listing 18-1. (cont.) 


USGI i5 
USGI i6 
USGI M 
USGI 18 


union -C 


USGI 


:8; 

• Bit; 

i; 



USGL Entry; 

r 


struct { 



USGI 

b1 

:1 

USGI 

b2 

:1 

USGI 

b3 

:1 

USGI 

b4 

:1 

USGI 

b5 

:1 

USGI 

b6 

:1 

USGI 

b7 

:1 

USGI 

b8 

:1 

USGI 

b9 

:1 

USGI 

b10 

:1 

USGI 

b11 

:1 

USGI 

b12 

:1 

USGI 

b13 

:1 

USGI 

bU 

:1 

USGI 

b15 

:1 

USGI 

b16 

:1 

USGI 

b17 

:1 

USGI 

b18 

:1 

USGI 

b19 

:1 

USGI 

b20 

:1 

USGI 

b21 

:1 

USGI 

b22 

:1 

USGI 

b23 

:1 

USGI 

b24 

:1 

USGI 

b25 

:1 

USGI 

b26 

:1 

USGI 

b27 

:1 

USGI 

b28 

;1 

USGI 

b29 

:1 

USGI 

b30 

:1 

USGI 

b31 

:1 

USGI 

b32 

:1 

> EntryBit; 

r 



> EntryUn; 


/* MSC high order bit */ 
/* unused bits */ 


/* MSC low order bit */ 


/* MSC high order bit */ 
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Listing 18-1. 

(cent.) 

for (iUn.i =0; iUn.i < 

256; iUn.i++) 



EntryUn. Entry = 0; 

/* zero out 

the value */ 

EntryUn.EntryBit.b32 = 

(iUn.Bit.i2 

A 

iUn.Bit. i8) ; 

EntryUn. EntryBit.b31 = 

(iUn.Bit.i1 

A 

iUn.Bit. i2 ^ 


iUn.Bit.i7 

A 

iUn.Bit.i8) ; 

EntryUn. EntryBit.b30 = 

(iUn.Bit.i1 

A 

iUn.Bit. 12 ^ 


iUn.Bit.i6 

A 

iUn.Bit. i7 ^ 


iUn.Bit.i8) 

’ 


EntryUn. EntryBit.b29 = 

(iUn.Bit.i1 

A 

iUn.Bit. 15 ^ 


iUn.Bi t. i6 

A 

iUn.Bit. i 7); 

EntryUn. EntryBit.b28 = 

(iUn.Bi t . i2 

A 

iUn.Bit.i4 ^ 


iUn.Bit.i5 

A 

iUn.Bit.i6 


iUn.Bit . i8) 



EntryUn.EntryBit.b27 = 

(iUn.Bit.i1 

A 

iUn.Bit. 12 ^ 


iUn.Bit.i3 

A 

iUn.Bit. i 4 ^ 


iUn.Bit.i5 

A 

iUn.Bit. 17 ^ 


iUn.Bi t. i8) 



EntryUn.EntryBit.b26 = 

(iUn.Bit.i1 

A 

iUn.Bit. 12 ^ 


iUn.Bit.i3 

A 

iUn.Bit. i 4 


iUn.Bi t. i6 

A 

iUn.Bit. i 7) ; 

EntryUn. EntryBit .b25 = 

(iUn.Bit.i1 

A 

iUn.Bit. 13 ^ 


iUh.Bit.i5 

A 

iUn.Bit.i6 


iUn.Bit.i8) 

r 


EntryUn. EntryBit.b24 = 

(iUn.Bit .i4 

A 

iUn.Bit.i5 ^ 


iUn.Bi t. i7 

A 

iUn.Bit . i8) ; 

EntryUn. EntryBit .b23 = 

( i Un . B i t . i 3 

A 

iUn.Bit. i4 


iUn.Bit.i6 

A 

iUn.Bit.i7) ; 

EntryUn. EntryBit.b22 = 

(iUn.Bit. i3 

A 

iUn.Bit.i5 


iUn.Bi t. i 6 

A 

iUn.Bi t. i8) ; 

EntryUn. EntryBit .b21 = 

(iUn.Bit. i 4 

A 

iUn.Bit.i5 


iUn.Bit. i7 

A 

iUn.Bit. i 8); 

EntryUn.EntryBit.b20 = 

(iUn.Bit .i2 

A 

iUn.Bit. i3 ^ 


iUn.Bit.i4 

A 

iUn.Bit. i6 ^ 


iUn.Bit. i7 

A 

iUn.Bit.i8); 

EntryUn. EntryBit .b1 9 = 

(iUn.Bit. i1 

A 

iUn.Bit.i2 ^ 


iUn.Bit . i3 

A 

iUn.Bit. i5 


iUn.Bit. i 6 

A 

iUn.Bit . i7) ; 

EntryUn. EntryBit. b18 = 

(iUn.Bit .i1 

A 

iUn.Bit. i2 ^ 
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Listing 18-1. (cont.) 


EntryUn.EntryBit.b1 7 


iUn.Bit.i4 

iUn.Bit.i6); 

(iUn.Bit.i1 

iUn.Bit.i4 


iUn.Bit.i5 ^ 

iUn.Bit.i3 ^ 
iUn.Bit.i5); 


EntryUn.EntryBi t .b16 
EntryUn.EntryBit.b1 5 
Ent ryUn . Ent ryBi t . b1 4 
EntryUn.EntryBi t .b1 3 


(iUn.Bit.i3 
iUn.Bit. i8) ; 
(iUn.Bit.i2 ^ 
iUn.Bit.i7) ; 
(iUn.Bit.i1 ^ 
iUn.Bit.i6); 
(iUn.Bit.i1 
iUn.Bit.i5); 


iUn.Bit.i4 ^ 
iUn.Bit.i3 ^ 
iUn.Bit.i2 ^ 


Ent ryUn . Ent ryBi t . b1 2 
EntryUn.EntryBi t .b11 
EntryUn.EntryBi t .b10 
EntryUn.EntryBit .b9 


(iUn.Bit.i4); 
(iUn.Bit.i3) ; 
(iUn.Bit.i8); 
(iUn.Bit.i2 
iUn.Bit.i8); 


iUn.Bit.i7 


EntryUn.EntryBit .b8 

EntryUn.EntryBi t .b7 
EntryUn.EntryBit .b6 

EntryUn.EntryBi t.b5 


(iUn.Bit.i1 ^ 
iUn.Bit.i7); 
(iUn.Bit.i5 ^ 
(iUn.Bit.i2 ^ 
iUn.Bit.i5 
(iUn.Bit.i1 ^ 
iUn.Bit.i4 


iUn.Bit.i6 ^ 

iUn.Bi t . i6) ; 
iUn.Bit.i4 
iUn.Bit.i8) ; 
iUn.Bit.i3 
iUn.Bi t . i7) ; 


EntryUn.EntryBi t.b4 

EntryUn.EntryBi t.b3 

Ent ryUn. Ent ryBi t.b2 
EntryUn.EntryBi t.bl 


(iUn.Bit.i2 
iUn.Bit . i6) ; 
(iUn.Bit.i1 ^ 
iUn.Bit . i5) ; 
(iUn.Bit. i1 ^ 
(iUn.Bi t . i3) ; 


iUn.Bit. i3 
iUn.Bit. i2 ^ 
iUn.Bit.i4); 


CrcTableCiUn.i ] = EntryUn. Entry; 

> 

> 


/* 


*/ 


void PrintTabLeO /* print out the look-up table */ 
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Listing 18-1. (cont.) 


for (i = 0; i < 256; i++) -C 
if ( ! (i % 4) ) 

printf("\n %02X - %08LX", i, CrcTabLeEi ] ) ; 

else 

printfC" %08LX", CrcTabLeCi 3) ; 

> 

> 


void LogoO 

printf("\n\n High Performance CRC-32 Computation Routine"); 
printf("\n Copyright 1988 W. David Schwaderer\n\n") ; 

> 

/*================== End of Program Logic ======================★ 


/* 

★ Program Output Start * 


00 

- 

00000000 

77073096 

EE0E612C 

990951 BA 

04 

- 

076DC419 

706AF48F 

E963A535 

9E6495A3 

08 

- 

0EDB8832 

79DCB8A4 

E0D5E91E 

97D2D988 

OC 

- 

09B64C2B 

7EB17CBD 

E7B82007 

90BF1D91 

10 

- 

1DB71064 

6AB020F2 

F3B97148 

84BE41DE 

14 

- 

1ADAD47D 

6DDDE4EB 

F4D4B551 

83D385C7 

18 

- 

136C9856 

646BA8C0 

FD62F97A 

8A65C9EC 

1C 

- 

14015C4F 

63066CD9 

FA0F3063 

8D080DF5 

20 

- 

3B6E20C8 

4C69105E 

D56041 E4 

A2677172 

24 

- 

3C03E4D1 

4B04D447 

D20D85FD 

A50AB56B 

28 

- 

35B5A8FA 

42B2986C 

DBBBC9D6 

ACBCF940 

2C 

- 

32D86CE3 

45DF5C75 

DCD60DCF 

ABD13D59 

30 

- 

26D930AC 

51DE003A 

C8D75180 

BFD06116 

34 

- 

21B4F4B5 

56B3C423 

CFBA9599 

B8BDA50F 

38 

- 

2802B89E 

5F058808 

C60CD9B2 

B10BE924 

3C 

- 

2F6F7C87 

58684C11 

Cl 611 DAB 

B6662D3D 

40 

- 

76DC4190 

01DB7106 

98D220BC 

EFD5102A 

44 

- 

71 B1 8589 

06B6B51F 

9FBFE4A5 

E8B8D433 

48 

- 

7807C9A2 

0F00F934 

9609A88E 

E10E9818 

4C 

- 

7F6A0DBB 

086D3D2D 

91646C97 

E6635C01 

50 

- 

6B6B51F4 

1C6C6162 

85653008 

F262004E 

54 

- 

6C0695ED 

1B01A57B 

8208F4C1 

F50FC457 

58 

- 

65B0D9C6 

12B7E950 

8BBEB8EA 

FCB9887C 

5C 

- 

62DD1DDF 

15DA2D49 

8CD37CF3 

FBD44C65 



216 


Part III: A CRC Treatise 


Listing 18-1. (cont.) 


60 

- 

4DB26158 

3AB551CE 

A3BC0074 

04BB30E2 

64 

- 

4ADFA541 

3DD895D7 

A4D1C46D 

03D6F4FB 

68 


4369E96A 

346ED9FC 

AD678846 

0A60B8D0 

6C 

- 

44042 D73 

33031 DE5 

AA0A4C5F 

D0007CC9 

70 

- 

5005713C 

270241 AA 

BE0B1010 

C90C2086 

74 

- 

5768B525 

206F85B3 

B966D409 

CE61E49F 

78 

- 

5EDEF90E 

29D9C998 

B0D09822 

C707A8B4 

7C 

- 

59B33D17 

2EB40D81 

B7BD5C3B 

COBA6CAO 

80 

- 

EDB88320 

9ABFB3B6 

03B6E20C 

74B1029A 

84 

- 

EAD54739 

9DD277AF 

04DB2615 

730C1683 

88 


E3630B12 

94643B84 

0D6D6A3E 

7A6A5AA8 

8C 

- 

E40ECF0B 

9309FF9D 

0A00AE27 

7D079EB1 

90 

- 

F00F9344 

8708A3D2 

1E01 F268 

6906C2FE 

94 

- 

F762575D 

806567CB 

196C3671 

6E6B06E7 

98 

- 

FED41B76 

89D32BE0 

10DA7A5A 

67004ACC 

9C 

- 

F9B9DF6F 

8EBEEFF9 

17B7BE43 

60B08E05 

AO 


D6D6A3E8 

A1D1937E 

38D8C2C4 

4F0FF252 

A4 

- 

D1BB67F1 

A6BC5767 

3FB506DD 

48B2364B 

A8 

- 

D80D2BDA 

AF0A1B4C 

36034AF6 

41047A60 

AC 

- 

DF60EFC3 

A867DF55 

316E8EEF 

4669BE79 

BO 

- 

CB61B38C 

BC66831A 

256FD2A0 

5268E236 

B4 


CC0C7795 

BB0B4703 

22021 6B9 

5505262F 

B8 

- 

C58A3B8E 

B2BD0B28 

2BB45A92 

5CB36A04 

BC 

- 

C2D7FFA7 

B5D0CF31 

2CD99E8B 

5B0EAE10 

CO 

- 

9B64C2B0 

EC63F226 

756AA39C 

026D930A 

C4 

- 

9C0906A9 

EB0E363F 

72076785 

05005713 

C8 

- 

95BF4A82 

E2B87A14 

7BB12BAE 

0CB61B38 

CC 

- 

92D28E9B 

E5DSBE0D 

7CDCEFB7 

0B0B0F21 

DO 

- 

86D3D2D4 

F1D4E242 

680DB3F8 

1 F0A836E 

D4 

- 

81BE16C0 

F6B9265B 

6FB077E1 

18B74777 

D8 

- 

88085AE6 

FF0F6A70 

66063BCA 

11010B5C 

DC 

- 

8F659EFF 

F862AE69 

616BFF03 

166CCF45 

EO 

- 

A00AE278 

070DD2EE 

4E048354 

3903B3C2 

E4 

- 

A7672661 

D06016F7 

49694740 

3E6E770B 

E8 

- 

AED16A4A 

D9D65ADC 

40DF0B66 

37D83BF0 

EC 

- 

A9BCAE53 

DEBB9EC5 

47B2CF7F 

30B5FFE9 

FO 

- 

BDBDF21C 

CABAC28A 

53B39330 

24B4A3A6 

F4 

- 

BAD03605 

CDD70693 

54DE5729 

230967BF 

F8 

- 

B3667A2E 

C4614AB8 

50681 B02 

2A6F2B94 

FC - B40BBE37 

TestArrayl CRC == 

C30C8EA1 5A05DF1B 

0x784DP132 

2002EF80 


Reversed CRC32 of TestArray1+its CRC == 0xDEBB20E3 
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Listing 18-1. (cont.) 

The CRC-32 CaLcuLation is correct... 

(TestArrayl + its CRC) Residual as Un-reversed Binary: 

==> 1100.0111 0000.0100 1101.1101 0111.1011 <== 

* Program Output End * 

*/ 
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Chapter 19 


Network Control Block 


As discussed in Chapters 3 and 4, applications access NetBIOS services 
using the Network Control Block (Neb) which is identical to the IBM To- 
ken-Ring’s Mcb. The following material assumes an IBM PC LAN Support 
Program implementation with one or more IBM LAN adapters present in 
a machine. In the case of more than one adapter, each adapter has its own 
NetBIOS interface and tables. 


Neb Fields 

Table 19-1 outlines the Neb format. USGC signifies unsigned char and 
USGI signifies unsigned int. Field names ending with indicate an 
offset: segment address field. The Chain Send command uses the Ncb- 
CallName field to specify the length and location of a second data buffer. 

NebCommand 

The NebCommand field is a 1-byte field specifying the NetBIOS com- 
mand. The high-order bit of the field specifies the command’s wait/no- 
wait option. 

The Wait/No- Wait Option 

If the high-order bit of the value in the NebCommand field is a binary 
zero, the wait option is specified (see Figure 19-1). Otherwise, the high- 


The material in this chapter and Chapter 20 is excerpted and paraphrased from IBM’s 
Technical Reference PC Network Manual, with the permission and courtesy of IBM. 
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Table 19-1. Neb Format 

Offset 

Field Name 

Len 

MASM 

Type 

C Type 

Description 

+00 +00h 

NcbCommand 

1 

DB 

USGC 

Command 

-1-01 -fOlh 

NcbRetCode 

1 

DB 

USGC 

Return code 

+02 -l-02h 

NcbLsn 

1 

DB 

USGC 

Local Session Number 

-(-03 -l-03h 

NebNum 

1 

DB 

USGC 

Name number 

+ 04 +04h 

NcbBuffer@ 

4 

DD 

char far * 

Buffer pointer 

+08 +08h 

NcbLength 

2 

DW 

USGI 

Buffer length (in bytes) 

+ 10 +0Ah 

NcbCallName 

16 

DB 

char[] 

Local/Remote NetBIOS name 

+26 +lAh 

NcbName 

16 

DB 

char[] 

Local NetBIOS name 

+ 42 +2 Ah 

NebRto 

1 

DB 

USGC 

Receive time-out value 

+ 43 +2Bh 

NebSto 

1 

DB 

USGC 

Send time-out value 

+44 +2Ch 

NcbPost@ 

.4 

DD 

void far *( ) 

Post routine pointer 

+ 48 +30h 

NebLanaNum 

1 

DB 

USGC 

Adapter number 

+ 49 +31h 

NcbCmdCplt 

1 

DB 

USGC 

Command status 

+ 50 +32h 

NebReserve 

14 

DB 

char[] 

Reserved area 


USGC = unsigned char. USGI = unsigned int. 


order bit is a binary one and the no- wait option is specified. The Cancel, 
Reset, and Unlink commands have only a wait option. 


|1— ► No-Wait I 
1 0— ►Wait 


□ Command Code El 






6 5 4 3 2 1 0 

i bit i::.::. ~:.:.z—:..zziC> 


Fig. 19-1. Format of the NcbCommand field. 


Selecting the wait option requests NetBIOS to return control when 
the adapter completes the command. In this sense, a no- wait NetBIOS 
option behaves like an ordinary application program subroutine call. 

When the command completes, the AL register and the NcbRetCode 
field contain the completion code. Care must be taken to assure that the 
command completes within a satisfactory period of time because Net- 
BIOS enters an enabled spin-loop and does not resume application pro- 
cessing until the command completes. 
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Selecting the no- wait option requests that NetBIOS return control to 
the application while the command is pending completion. The post 
routine, if specified, is given control when the adapter completes the 
command. 

Selecting the no- wait option allows maximum throughput by permit- 
ting several simultaneous pending commands. However, while a com- 
mand is pending, application programs must not change either the Neb 
or any data field (e.g., the post routine address) associated with the com- 
mand. 

Immediate and Final Return Codes 

When the no-wait option is selected, two return codes may be returned. 
The first return code, referred to as the immediate return code, returns 
after the command is initially scanned by NetBIOS. The other return 
code, referred to as the final return code, returns when the command is 
completed. 

If the first return code is not OOh, NetBIOS has rejected the command 
and does not proceed with processing the command. In this instance, 
NetBIOS does not provide a second return code, nor does it invoke a 
post routine. In any case, all immediate return codes are also valid final 
return codes. 


NebRetCode 

The NebRetCode field is a l-byte field containing a value of FFh while a 
no- wait option is pending. It also contains the command’s final comple- 
tion code when NetBIOS completes the command. 

If the no- wait option is used without specifying a post routine, both 
the NcbCmdCplt field and the NebRetCode field contain the final return 
code after command completion: 

• A return code value of OOh indicates successful command comple- 
tion. 

• Return code values of 1 through 254 (FEh) indicate an unsuccess- 
ful command completion. 

Applications should never loop on the NebRetCode field looking for com- 
mand completion; they should loop on the NcbCmdCplt field. This is be- 
cause the NebRetCode field is set before the NcbCmdCplt field is set. 

After completing the NebRetCode field, the Neb may be placed on an 
internal NetBIOS POST processing queue. The NcbCmdCplt is not set un- 
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til the Neb is dequeued from the POST processing queue. This applies to 
all Nebs that have a no-wait option, even if the post routine address is 
0000:0000. In the case that the post routine address is 0000:0000, the Neb 
is dequeued and the determination is made not to invoke a post routine. 


NcbLsn 

The NcbLsn field is a l-byte field referring to an existing Local Session 
Number (LSN). The LSN value must be between 1 and 254 (FEh) inclu- 
sive. NetBIOS assigns the LSN value in an incremental, modulo 255, 
roundrobin manner. The values zero and 255 (FFh) are never assigned. 

An LSN value is valid only after a Call or Listen command successfully 
completes and is a session number the local application has with another 
application. It is logically equivalent to an application’s open file-handle. 
The applications may be local or remote, and the LSN value assigned to 
one side of a session is independent of the value assigned to the other 
side. Two adapters within the same machine may have sessions with the 
same LSN value, but they are differentiated by their adapter’s NcbLana- 
Num values. 

The NcbLsn field is required for Send, Chain Send, Receive, Receive- 
Any and Hang Up commands but is not used for datagram commands. 
For Reset commands, the NcbLsn value can specify the maximum num- 
ber of sessions NetBIOS allows for the adapter. (See the Reset command 
description in Chapter 20 for details.) 


NebNum 

The NebNum field is a 1-byte field that NetBIOS completes after an Add 
Name or Add Group Name command successfully completes. This num- 
ber, and not its associated name, is used with all Receive-Any commands 
and all datagram commands. NetBIOS assigns the value of NebNum in an 
incremental, modulo 255, roundrobin manner. The values zero and 255 
(FFh) are never assigned and the value 01 h is always used by the perma- 
nent node name. 

For Reset commands, the NebNum value can specify the maximum 
number of pending commands the NetBIOS allows for the adapter. (See 
the Reset command description in Chapter 20 for details.) Specifying an 
NebNum value of FFh with Receive-Any and Receive Datagram com- 
mands indicates that data can be received for any existing session or reg- 
istered name, respectively. 
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NcbBuffer@ 

The NcbBuffer® is a 4-byte field containing the address of an application 
buffer. This field is in offset;segment format and must be a valid memory 
address. 

For Adapter Status and Session Status commands, the NcbBuffer® 
field contains the address where NetBIOS should place the information 
it returns. The NcbLength field specifies the length of the buffer. 

For Cancel commands, the NcbBuffer® field points to an Neb that 
should be canceled. 

For Chain Send, Send, Send Datagram, and Send Broadcast Datagram 
commands, the NcbBuffer® field specifies the address where the data 
resides that should be transmitted. The NcbLength field specifies how 
much data should be sent. 

For Receive, Receive-Any, Receive Datagram, and Receive Broadcast 
Datagram commands, the NcbBuffer® field specifies the address where 
received data should be placed; the NcbLength field specifies how much 
data should be placed at that location. 


NcbLength 

The NcbLength field is a 2-byte field indicating the length, in bytes, of an 
application receive or transmission buffer. 

For Chain Send, Send, Send Datagram, and Send Broadcast Datagram 
commands, an application uses the NcbLength field to indicate the num- 
ber of bytes to send. 

For Receive, Receive-Any, Receive Datagram, Receive Broadcast 
Datagram, Adapter Status, and Session Status commands, an application 
uses the NcbLength field to indicate the size of the data-receive buffer. 
For these commands, NetBIOS updates the NcbLength field with the 
number of bytes actually received when the commands complete. 


NcbCallName 

The NcbCallName field is a l6-byte field containing a network name or 
second application buffer specification. 

For Call, Listen, and Send Datagram commands, an application 
places a name the application wants to communicate with in the Ncb- 
CallName field. Usually the name is a remote name, though the name can 
be a local name for local sessions. 
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In the case of a Listen command, placing an asterisk (*) in the first 
position of the NcbCallName (byte 0) indicates that the Listen can be sat- 
isfied by any Call to the name specified in the NcbName field. 

In the case of an Adapter Status command, placing the asterisk in the 
first position of the NcbCallName (byte 0) indicates that the Adapter Sta- 
tus command is for a local adapter. 

For a Chain Send command, an application uses the NcbCallName 
field to specify the si2e and location of a second application buffer. In 
this case, only the first six bytes of the NcbCallName field are used and 
the others ignored. The first two bytes (bytes 0 and 1) specify the second 
buffer’s length and the remaining four bytes (bytes 2 and5)are the offset: 
segment address of the second buffer. 


NcbName 

The NcbName field is a l6-byte field containing a local network name. 

For Add Name and Add Group Name commands, the NcbName field 
contains a name for which the application is requesting network registra- 
tion. For the Delete Name command, the field contains a name that the 
application is requesting to be deleted from the NetBIOS name table. 

For Call or Listen commands, the field contains a local network name 
that the application wishes to use to conduct a session. 

For Session Status commands, placing the asterisk in the first byte 
(byte 0) of the NcbName field indicates that NetBIOS should return data 
for all sessions that the adapter currently supports. 

Applications may use permanent node names as names. NetBIOS 
constructs permanent node names by appending the 6 bytes of an 
adapter’s permanent ID ROM value to 10 bytes of binary zeros. The maxi- 
mum number of names that an adapter may be known by is determined 
by the config.sys DXMTOMOD.SYS NAMES parameter. This value does 
not include the permanent node name as one of its entries. 


NcbRto 

The NcbRto field is a l-byte field used by Call and Listen commands to 
specify time-out periods for Reeeive-Any and Receive commands associ- 
ated with a requested, but yet unestablished, session. 

A nonzero value specifies a time-out period in increments of 1/2 
seconds. For example, a value of 255 (FFh) indicates a time-out period of 
127.5 seconds. A value of OOh indicates there is no time-out. 
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Time-out periods may vary for each session, but are fixed for a given 
session and are not changeable once the session is established. In addi- 
tion, time-out periods for both sides of a session may be different. 

Unlike Send and Chain Send time-out expirations, if a Receive-Any or 
Receive command’s time-out period expires, the session does not termi- 
nate (see NcbSto). 


NcbSto 

The NcbSto field is a l-byte field that Call and Listen commands use to 
specify a time-out period for all Send and Chain Send commands associ- 
ated with a requested, but yet unestablished, session. It has no effect on 
Send No-Ack and Chain Send No-Ack commands. 

A nonzero value specifies a time-out period in increments of 1/2 
seconds. For example, a value of 255 (FFh) indicates a time-out period of 
127.5 seconds. A value of OOh indicates there is no time-out. 

Time-out periods may vary for each session, but are fixed for a given 
session and are not changeable once the session is established. In addi- 
tion, the time-out periods for both sides of a session may be different. 

Send and Chain Send time-outs should be used with caution because 
they terminate the session when they expire. Canceling Send and Chain 
Send commands with a Cancel command also terminates the session as- 
sociated with the canceled commands. 


NcbPost@ 

The NcbPost® field is a 4-byte field pointing to a routine, referred to as 
the post routine, NetBIOS executes when it accepts and subsequently 
completes. 

The NcbPost® field only applies to no-wait option and is ignored 
when the wait option is specified. This field uses an offset:segment for- 
mat. If the post address is all zeros, NetBIOS does not call a post routine. 
In this case, the application must check the NcbCmdCplt field for a 
change from a value of FFh. 

Alternatively, the post address is not all zeros and NetBIOS calls the 
post routine as an interrupt. NetBIOS enters the routine with the AL reg- 
ister set to the return code, the CS: IP registers set to the post routine en- 
try point, and the ES;BX registers pointing to the completed Neb. Post 
routine entry is made in a disabled state and the post routine should re- 
turn to NetBIOS with an IRET instruction. 
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The post routine does not have to save or restore registers and can 
issue NetBIOS requests. However, it should not issue PC-DOS requests 
because PC-DOS is not reentrant and such a request may have been inter- 
rupted to invoke the post routine. 


NcbLanaNum 

The NcbLanaNum field is a l-byte field indicating which adapter card 
NetBIOS should use to process the command. 

The NcbLanaNum must contain either OOh for the first (primary) 
adapter or 01 h for the second (alternate) adapter. The adapter must be 
initialized for the appropriate primary/alternate setting. The NcbLana- 
Num values 02h and 03h are reserved for IBM PC LAN adapters. 


NcbCmdCplt 

The NcbCmdCplt field is a 1-byte field indicating the status of a pending 
no- wait option command. A value of FFh signifies the command is still 
pending. Any other value indicates that the command has completed; 
the value is the final return code. 

If a no-wait option is specified and the NcbPost® is all zeros, Net- 
BIOS places the command return code in both the NcbRetCode and the 
NcbCmdCplt fields when Neb processing is complete. Applications 
should loop on the NcbCmdCplt field looking for command comple- 
tion; they should never loop on the NcbRetCode field. 


NebReserve 

The NebReserve field is a l4-byte reserved area. NetBIOS uses this field 
for Neb processing and to return extended error information. 


Command Completion 

When an application presents an Neb to NetBIOS, NetBIOS provides a 
return code to the requesting application. The particular way it does this 
depends on whether the command specifies a wait option or a no- wait 
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option. If the NcbCommand high-order bit has a value of binary 1, the 
no-wait option is selected. Otherwise, the wait option is specified. 


Wait Option 

If a command specifies a wait option, control does not return to the ap- 
plication until the adapter completes the command. When the command 
completes, the final return code is in the AL register as well as the Ncb- 
RetCode and NcbCmdCplt fields. Control returns to the instruction im- 
mediately following the NetBIOS request interrupt. 


No- Wait Option 

If a command specifies a no-wait option, NetBIOS presents two return 
codes. After initially scanning the Neb, control returns to the instruction 
immediately following the NetBIOS request interrupt with an immediate 
return code in the AL register. If the immediate return code is not OOh, 
the adapter cannot successfully execute the command. 

If the Immediate return code is OOh, the adapter queues the request 
pending final completion and provides a final return code when the 
adapter completes the command. If the NebPost® field of the Neb is 
zero, NetBIOS places the final return code in the NcbCmdCplt field, 
which must be checked for change by the application program. 

If the application checks the NcbCmdCplt field, a value other than 
FFh indicates command completion and this value is the final return 
code. Applications should never loop on the NebRetCode field looking 
for command completion, but rather on the NcbCmdCplt field because 
the NebRetCode field is set first. After completing the NebRetCode field, 
the Neb may be placed on an internal NetBIOS POST processing queue. 
The NcbCmdCplt is not set until the Neb is dequeued from the POST 
processing queue. This applies to all Nebs that have a no-wait option, 
even if the post routine address is 0000:0000. In the case that the post 
routine address is 0000:0000, the Neb is dequeued and the determina- 
tion is made not to invoke a post routine. 

No- Wait Option with a Post Routine 

If the NebPost® field is not zero, NetBIOS sets the final return code in 
both the AL register and the NebRetCode field. NetBIOS then saves its reg- 
isters, points the ES:BX register pair at the completed Neb, pushes the 
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flags, disables maskable interrupts, and executes a far call to the post rou- 
tine. 

In the application post routine, the final return code may be obtained 
from either the AL register or the NcbRetCode field. The post routine 
should return to NetBIOS with an IRET instruction. The post routine 
does not have to save or restore registers and can issue NetBIOS requests. 
However, it should not issue PC-DOS requests because PC-DOS is not 
reentrant and such a request may have been interrupted to invoke the 
post routine. 

No- Wait Option with No Post Routine 

If the NcbPost® field is zero, no post routine is specified. The final re- 
turn code is in both the NcbCmdCplt field and in the NcbRetCode field. 
Again, applications should never loop on the NcbRetCode field looking 
for command completion, but should monitor the NcbCmdCplt field to 
see when it changes from a value of OFFh. 



Chapter 20 


NetBIOS Commands 


The following information applies to NetBIOS requests for PC-DOS and 
NetBIOS. Appendix F contains additional information for OS/2 NetBIOS 
requests. 

The Commands 

Adapter Status 33h Wait; B3h No-Wait 



In 

Out 

Immediate Return Codes 

1 

NcbCommand 

X 


OOh 03h 

NcbRetCode 


X 

21h 22h 23h 

NcbLsn 



4Xh 

NcbNum 



50h-FEh 

NcbBuffer® 

X 



NcbLength 

X 

X 


NcbCallName 

X 


Final Return Codes 

NcbName 

i 



NcbRto 



OOh 01 h 03h 05h 06h OBh 

NcbSto 



19h 

NcbPost® 



21h22h23h 

NcbLanaNum 

X 


4Xh 

NcbCmdCplt 


X 

50h-FEh 

NcbReserve 


? 
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The Adapter Status command requests the NetBIOS status of either a lo- 
cal or remote adapter. 

The NcbCallName field specifies from which adapter to obtain the 
status. The field may contain a permanent node name, group name, or 
unique name. If the first byte of the NcbCallName field contains an aster- 
isk (*), the local NetBIOS status of the adapter specified by the Nc- 
bLanaNum field returns. The status information returns in the buffer 
pointed to by the NcbBuffer® field. 

The minimum buffer size is 60 bytes. The maximum status informa- 
tion size is 60 plus 18 times the maximum number of names. The maxi- 
mum number of names is determined by the adapter’s IBM LAN Support 
Program NAMES parameter. 

A message incomplete status (06h) returns for two reasons; 

1 . The buffer is not large enough to hold all the generated data. 

2 . The status information generated for a remote Adapter Status com- 
mand exceeds the maximum datagram length. 

In either case, the final amount of data returning in the buffer is the lesser 
of the buffer’s size or the maximum datagram length. 


Token-Ring Adapter Status Information Format 

I-Frame is an IEEE 802.2 term for an information frame, which is used in 
session communication. LLC logic transmits I-Frames and signifies their 
receipt with an acknowledgment (ACK). 

UTFrame is an IEEE 802.2 term for an unnumbered information 
frame, used for datagrams and query frames. LLC logic transmits UT 
Frames but does not acknowledge their receipt with an ACK. 

An appendage is similar to a NetBIOS post routine. It is defined by 
the CCB adapter handler interface. (Neb commands are broken into CCB 
commands and passed to the adapter handler logic for processing.) Ap- 
pendages are executed as part of CCB command completion processing. 

The CCB DIR.OPEN.ADAPTER command RING. STATUS. APPEND- 
AGE field pointer identifies an appendage. NetBIOS issues a DIR. OPEN. 
ADAPTER specifying a RING. STATUS. APPENDAGE as part of the com- 
mand and uses the appendage to update status counters. However, Net- 
BIOS does not open the adapter if it is already open. In that case, 
NetBIOS does define a RING.STATUS.APPENDAGE and consequently 
has no way of updating the status counters. In any event, there can only 
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be one RING. STATUS. APPENDAGE for an adapter and there is no way for 
any other application to determine who owns it. 

The Frame Rejected Receive Count is the number of received and re- 
jected I-Frames. The maximum-size I-Frame used in a session is the small- 
est DHB.SIZE of the two communicating adapters and is determined at 
session start-up. Received I-Frames larger than the maximum value are 
received and rejected by LLC logic. When NetBIOS is used, the Frame 
Rejected Receive Count should always have a value of zero. 

The Frame Rejected Transmit Count is the number of I-Frames re- 
jected before transmission. The maximum-size I-Frame used in a session 
is the smallest DHB.SIZE of the two communicating adapters and is de- 
termined at session start-up. Requests to transmit I-Frames larger than the 
maximum value are rejected by LLC logic. When NetBIOS is used, the 
Frame Rejected Transmit Count should always have a value of zero. 

The I-Frame Receive Error Count normally indicates the number of 
I-Frames received out of sequence. In this event, LLC logic enters a 
checkpointing state to establish data integrity. 

The Transmit Abort Count should always have a value of zero since 
there is no way to abort a transmission. 

The Successful Frame Transmit/Receive Count value includes the 
number of successfully transmitted/received I-Frames and UI-Frames. 

The I-Frame Transmit Error Count is similar to the I-Frame Receive Er- 
ror Count except that it reflects the number of out-of-sequence frames that 
were sensed by other adapters. This value may be nonzero since I-Frames 
may disappear before arriving at their destination, subsequently causing 
the next successfully arriving frame to appear out of sequence. The check- 
pointing sequence informs the local adapter the condition has occurred. 

The Remote Request Buffer Depletion Count indicates the number of 
times NetBIOS has run out of SAP buffers. Because this cannot happen, 
this value should always be zero. Otherwise, this is a NetBIOS error. 

The Expired T1 Timer Count indicates the number of times the Re- 
sponse Timer has expired. The response timer expires when a local link 
station has transmitted DLC.MAXOUT frames without receiving an ACK. 
In this event, the LLC logic enters checkpointing and requests an ACK 
from the remote link station. An excessive Expired T1 Timer Count value 
indicates an adjustment is required. 

The Expired Ti Timer Count indicates the number of times the inac- 
tivity timer has expired. The inactivity timer expires when there is no 
activity on the session. The count is informational only and is no cause 
for concern. The returned Token-Ring Adapter Status command informa- 
tion is summarized in Table 20-1. All counters, except for the remote re- 
quest buffer depletion count counter, roll over from F...Fh to 0...0h. 
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Table 20-1. Token-Ring Adapter Status Information Format 
Offset Size MASM C Field Contents 


+ 00 +00h 

6 

DB 

char 

+ 06 +06h 

1 

DB 

USGC 

+ 07 +07h 

1 

DB 

USGC 

+ 08 +08h 

1 

DB 

USGC 

+ 09 +09h 

1 

DB 

USGC 

+ 10 +0Ah 

2 

DW 

USGI 

+ 12 +0Ch 

2 

DW 

USGI 

+ 14 +0Eh 

2 

DW 

USGI 

+ 16 + lOh 

2 

DW 

USGI 

+ 18 +12h 

2 

DW 

USGI 

+20 +I4h 

4 

DW 

USGL 

+24 +18h 

4 

DW 

USGL 

+28 +lCh 

2 

DW 

USGI 

+30 +lEh 

2 

DW 

USGI 

+ 32 +20h 

2 

DW 

USGI 

+34 +22h 

2 

DW 

USGI 

+36 +24h 

4 

DD 

far * 

+40 +28h 

2 

DW 

USGI 

+ 42 +2 Ah 

2 

DW 

USGI 

+44 +2Ch 

2 

DW 

USGI 

+ 46 +2Eh 

2 

DW 

USGI 

+ 48 +30h 

2 

DW 

USGI 

+ 50 +32h 

2 

DW 

USGI 

+ 52 +34h 

2 

DW 

USGI 

+54 +36h 

2 

DW 

USGI 

+ 56 +38h 

2 

DW 

USGI 

+ 58 +3Ah 

2 

DW 

USGI 

+60 +3Ch 

?? 




Permanent node name [6] 

NetBIOS major version number (low- 
order nibble-only) 

Always set to zero 

Lan adapter type 

Minor version number 

Reporting period in minutes 

Frame rejected receive count 

Frame rejected transmit count 

I-Frame receive error count 

Transmit abort count 

Successful frame xmit count 

Successful frame receive count 

I-Frame transmit error count 

Remote request buffer depletion count 

Expired T1 timer count 

Expired Ti timer count 

Local extended status information 
pointer 

Free command blocks 
Current maximum pending Nebs 
Maximum commands 
Transmit buffer depletion count 
Maximum datagram packet size 
Pending session count 
Maximum pending session count 
Maximum sessions 
Maximum session packet size 
Name Table entry count 
Name Table entry(ies) 


The Token-Ring extended status information address field at offset 36 
(24h) is valid only for local status commands; the field’s value is unde- 
fined for remote status commands. The field points to the fixed memory 
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location of adapter-specified status. An application program should not 
modify the data, though it can inspect and use it. The extended status 
information address field has the following format; 

Bytes 00-01: DIR. INITIALIZE bring-up error code 

Bytes 02-03: DIR. OPEN. ADAPTER error code 

Bytes 04-05: Latest ring status 

Bytes 06-07 ; Latest adapter check reason code 

Bytes 08-09: Latest PC-detected error (from the AX register) 

Byte 10: Latest operational error code (4X or 5X) 

Byte 11 : Return code of latest implicit CCB command 

Bytes 12-13: Line errors 

Bytes 14-15: Internal errors 

Bytes 16-17: Burst errors 

Bytes 18-19: A/C error 

Bytes 20-21: Abort delimiter 

Bytes 22-23: Reserved 

Bytes 24-25; Lost frame 

Bytes 26-27: Receive congestion 

Bytes 28-29: Frame copied errors 

Bytes 30-31: Frequency errors 

Bytes 32-33; Token errors 

Bytes 34-35: Reserved 

Bytes 36-37: Reserved 

Bytes 38-39: Reserved 

When NetBIOS initializes, DIR. INITIALIZE and DIR. OPEN. 
ADAPTER commands are sometimes executed followed by a DLC.OPEN. 
SAP command. Byte 10 provides the last of the executed CCB command 
codes and byte 11 contains its CCB return code. Bytes 10 and 11 help de- 
termine conditions resulting in certain 4Xh return codes. 

Adapter counters (bytes 12 through 39) are valid only if a ring status 
appendage is defined and wraps from FFFFh to OOOOh. When no ap- 
pendage is defined, these counters are updated when a ring status 
counter overflow is reported. These counters are the same as obtained 
with a DIR.READ.LOG command through any application program. Is- 
suing a DIR.READ.LOG command resets these counters. If an appendage 
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is defined, it is the application’s responsibility to maintain the adapter 
counters. The number of pending sessions (offset 50) is computed using 
the following procedure; 

Pending sessions are 

• pending Call and Listen commands 

• pending and completed Hang Up commands 

• established and aborted sessions 

Each NetBIOS local name table (offset 60) entry is 18 bytes long and has 
the following format: 

• The first 16 bytes (bytes 0-15) contain a NetBIOS name that has 
been added with an Add Name or Add Group Name command. 
The permanent node name is not included in the NetBIOS name 
table entries, but is reported separately. 

• The 17th byte (byte 16) is the name’s NetBIOS name number 
(NcbNum). 

• The 18th (byte 17) byte is ANDed with 87h to provide the name’s 
status. 

Possible status values are (x = reserved bit, N = 0 if the name is a unique 
name, and N = 1 if the name is a group name); 

NxxxxOOO: The name is in the registration process 
NxxxxlOO: The name is registered 
NxxxxlOl: The name is deregistered 
NxxxxllO; The name is a detected duplicate name 

Nxxxxlll: The name is a detected duplicate name that is pending 
deregistration 

Registered Name: If a name is a registered name, it has been added to 
the local NetBIOS name table. 

Deregistered Name: If a name is a deregistered name, a Delete Name 
command was issued for it while it had active session(s). When a name is 
deregistered, NetBIOS does not permit subsequent Call or Listen com- 
mands to use the name. After the session(s) terminates, NetBIOS removes 
the name from the local NetBIOS name table and the name can be added 
again for use by Call and Listen commands. 

Duplicate Name: If a name is a detected duplicate name, it is a unique 
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name added to two different NetBIOS name tables as a result of a net- 
work error. Duplicate names should be deleted as soon as they are de- 
tected. 


PC Network Adapter Status Information Format 

The returned PC Network Adapter Status command information has the 
format outlined in Table 20-2. The PC Network LANA adapter’s external 
jumper status is illustrated in Figure 20-1. 


W2 

W1 

X 

X 

X 

X 

X 

X 

7 

^ 

6 

5 

4 

3 

2 

1 

0 


W2 = 1 -► W2 Jumper on adapter (RPL-disabled) 

W2 = O-^ W2 Jumper off adapter (RPL-enabled) 

W1 = 1 -► W1 Jumper on adapter (reserved) 

W1 = O-^ W1 Jumper off adapter (reserved) 

Fig. 20-1. Format of the external jumper status field. 

The self test results values are 

80h: Successful completion 
81 h: Processor test failed 
82h; ROM checksum test failed 
83h; Unit ID Prom test failed 
84h: RAM test failed 
85h; Host interface test failed 
86h: +!— 12V test failed 
87h: Digital loopback test failed 
8Eh: Possible constant carrier 
8Fh: Analog loopback test failed 

When the reporting period, collision count, aborted transmission, 
successful transmission, successful receive, and retransmission counters 
reach FFFFh, they roll over to OOOOh. When the CRC error, alignment 
error, and resource depletion counters reach FFFFh, they do not roll over 
to OOOOh. 
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Table 20-2. PC Network LANA Adapter Status Information Format 


Offset Size MASM C Field Contents 


+00 +00h 

6 

DB 

USGC 

+ 06 +06h 

1 

DB 

USGC 

+ 07 +07h 

1 

DB 

USGC 

+08 +08h 

1 

DB 

USGC 

+ 09 +09h 

1 

DB 

USGC 

+ 10 +0Ah 

2 

DW 

USGI 

+ 12 +0Ch 

2 

DW 

USGI 

+ 14 +0Eh 

2 

DW 

USGI 

+ 16 + lOh 

2 

DW 

USGI 

+ 18 +12h 

2 

DW 

USGI 

+20 + l4h 

4 

DD 

USGL 

+ 24 +18h 

4 

DD 

USGL 

+28 +lCh 

2 

DW 

USGI 

+ 30 +lEh 

2 

DW 

USGI 

+ 32 +20h 

1 

DB 

char 

+ 40 +28h 

2 

DW 

USGI 

+42 +2Ah 

2 

DW 

USGI 

+44 +2Ch 

2 

DW 

USGI 

+46 +2Eh 

1 

DB 

char 

+ 50 +32h 

2 

DW 

USGI 

+ 52 +34h 

2 

DW 

USGI 

+ 54 +36h 

2 

DW 

USGI 

+ 56 +38h 

2 

DW 

USGI 

+ 58 +3Ah 

2 

DW 

USGI 

+60 +3Ch 

?? 




Permanent node name [6] 

External jumper setting 
Self test results 

Adapter protocol layer major version 
number 

Adapter protocol layer minor version 
number 

Reporting period in minutes (rolls 
over) 

CRC error count (does not roll over) 
Alignment errors (does not roll over) 
Collision count (rolls over) 

Transmit abort count (rolls over) 
Successful transmits (rolls over) 
Successful receives (rolls over) 
Retransmit count (does not roll over) 
Resource depletion count 
Reserved areal [8] 

Free command blocks 
Current maximum Nebs 
Hardware maximum command blocks 
Reserved area2 [4] 

Pending session count 

Current maximum pending sessions 

Hardware maximum session count 

Maximum packet size 

NetBIOS name table entry count 

struct NetBIOS name table entry(ies) 

[ 16 ] 


The local name table entries have the same format as discussed in the 
Token-Ring Adapter Status command. 
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Add Group Name 


36h Wait; B6h No-Wait 



In 

Out 

NcbCommand 

X 


NcbRetCode 

NcbLsn 


X 

NcbNum 

NcbBuffer® 

NcbLength 

NcbCallName 


X 

NcbName 

NcbRto 

NcbSto 

X 


NcbPost® 

1 

? 


NcbLanaNum 

X 


NcbCmdCplt 


X 

NcbReserve 


p 


Immediate Return Codes 

OOh 03h 
21h 22h 23h 
4Xh 

50h-FEh 


Final Return Codes 

OOh 03h ODh OEh 
15h l6h 19h 
21h 22h 23h 
4Xh 

50h-FEh 


The Add Group Name command adds a nonunique l6-character name 
that the network adapter is known by to an adapter’s NetBIOS name ta- 
ble. The name cannot be used as a unique name, but can be used as a 
group name, by any other network adapter. 

NetBIOS processes this command by repeatedly broadcasting a 
network name query. The number of times it transmits the query is 
determined by the config.sys DXMTOMOD.SYS TRANSMIT. COUNT 
parameter. 

If no reply to a name query request is received after a period deter- 
mined by the config.sys DXMTOMOD.SYS TRANSMIT.TIMEOUT pa- 
rameter, another name query is broadcast until TRANSMIT.COUNT 
queries have occurred. If still no reply has arrived, NetBIOS assumes the 
name is nonunique and adds it to the local NetBIOS name table as a 
group name. 

The adapter returns the number of the name in the NcbNum field. 
This number is used in datagram support and for Receive-Any com- 
mands. 
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Add Name 


30h Wait; BOh No-Wait 



In 

Out 

NcbCommand 

X 


NcbRetCode 

NcbLsn 


X 

NcbNum 

NcbBuffer® 

NcbLength 

NcbCallName 


X 

NcbName 

NcbRto 

NcbSto 

X 


NcbPost® 

? 


NcbLanaNum 

X 


NcbCmdCplt 


X 

NcbReserve 

i 

? 


Immediate Return Codes 

OOh 03h 
21h 22h 23h 
4Xh 

50h-FEh 


Final Return Codes 

OOh 03h ODh OEh 
15h l6h 19h 
21h22h23h 
4Xh 

50h-FEh 


The Add Name command adds a unique l6-character name to an 
adapter’s NetBIOS name table. This is a name the adapter is known by 
and must be unique across the network. 

NetBIOS processes this command by repeatedly broadcasting a 
network name query. The number of times it transmits the query is 
determined by the config.sys DXMTOMOD.SYS TRANSMIT.COUNT 
parameter. 

If no reply to a name query request is received after a period deter- 
mined by the config.sys DXMTOMOD.SYS TRANSMIT.TIMEOUT pa- 
rameter, another name query is broadcast until TRANSMIT.COUNT 
queries have occurred. If still no reply has arrived, NetBIOS assumes the 
name is unique and adds it to the local NetBIOS name table as a unique 
name. 

The adapter returns the number of the name in the NcbNum field. 
This number is used in datagram support and for Receive-Any com- 
mands. 
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Call 


In Out 


NcbCommand 

X 


NcbRetCode 


X 

NcbLsn 


X 

NcbNum 



NcbBuffer® 



Neb Length 



NcbCallName 

X 


NcbName 

X 


NcbRto 

X 


NcbSto 

X 


NebPost® 

p 


NebLanaNum 

X 


NcbCmdCplt 


X 

NebReserve 


? 


lOh Wait; 90h No-Wait 

Immediate Return Codes 

OOh 03h 
21h 22h 23h 
4Xh 

50h-FEh 


Final Return Codes 

OOh 03h 05h 09h OBh 
llh 12h I4h 15h 18h 19h 
21h 22h 23h 
4Xh 

50h-FEh 


The Call command opens a session with a destination name specified by 
the NcbCallName field. The command uses a local name specified by the 
NcbName field. The destination name adapter must have a Listen com- 
mand pending for successful session establishment. 

Sessions may be established between any valid names whether they 
are local or remote names. Multiple sessions may be established with the 
same pair of names or even with the same name. All Send (and Chain 
Send) or Receive commands for sessions abort if they do not complete 
before their specified session time-out intervals expire (NcbSto and 
NcbRto, respectively). For session Send and Chain Send, this aborts the 
session. The session time-out intervals are specified in 1/2 second units. 
(A value of zero means that no time-out occurs.) 

A Call fails if it is not successful before the system time-out expires. 
The system time-out is calculated by multiplying the system interval and 
system retry count. The values are NetBIOS constants that are deter- 
mined by the config.sys DXMTOMOD.SYS TRANSMIT.TIMEOUT and 
TRANSMIT.COUNT parameters, respectively. 

When a Call is completed, NetBIOS assigns a Local Session Number 
(LSN) to the established session. NetBIOS assigns the LSN value in an in- 
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cremental, modulo 255, roundrobin manner. The values zero and 255 
are never assigned. The LSN value must be between 1 and 254 (FEh) in- 
clusive. 


Cancel 


35h Wait 


In Out Final Return Codes 


NcbCommand 

NcbRetCode 

NcbLsn 

NcbNum 

NcbBuffer@ 

NcbLength 

NcbCallName 

NcbName 

NcbRto 

NcbSto 

NcbPost® 

NcbLanaNum 

NcbCmdCplt 

NcbReserve 


X 

X 

X 


X 

X 


? 


OOh 03h 
23h 24h 26h 
4Xh 

50h-FEh 


The Cancel command cancels the NetBIOS command, whose Neb is at 
the address given by NebBuffer®. Canceling pending Send or Chain 
Send commands always aborts their respective session, though you can 
cancel their No-Ack variants without aborting their respective sessions. 
You cannot cancel the following NetBIOS commands: 



Add Group Name 
Add Name 
Cancel 
Delete Name 
Reset 

Send Datagram 

Send Broadcast Datagram 

Session Status 

Unlink 
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Chain Send 
Chain Send No-Ack 


In Out 


NcbCommand 

X 


NcbRetCode 


X 

NcbLsn 

X 


NcbNum 



NcbBuffer® 

X 


NcbLength 

X 


NcbCallName* 

X 


NcbName 



NcbRto 



NcbSto 



NcbPost® 

p 


NcbLanaNum 

X 


NcbCmdCplt 


X 

NcbReserve 

1 

? 


17h Wait; 97h No-Wait 
72h Wait; F2h No-Wait 

Immediate Return Codes 

OOh 03h 
21h 22h 23h 
4Xh 

50h-FEh 


Final Return Codes 

OOh 03h 05h 07h 08h OAh OBh 
18h 

21h22h23h 

4Xh 

50h-FEh 


The Chain Send No-Ack command is a variant of the Chain Send com- 
mand. Its differences are discussed in Appendix E. 

The Chain Send command sends data on the session specified by the 
NcbLsn field value. The data is in two independent buffers pointed to by 
the NcbBuffer® and the NcbCallName fields. NetBIOS concatenates the 
second buffer’s data to the first buffer’s data and sends the aggregate data 
as a single, seamless message. Each buffer can contain between zero and 
64K-1 bytes inclusive. 

The first 6 bytes of NcbCallName field specify the length (2 bytes) 
and address (4 bytes) of the second buffer in offset; segment format. 
When the remote side of the session closes a session with a Hang Up, all 
local Chain Send commands pending for the closed session return with a 
session-closed status. 

If a local Hang Up command is issued with session-pending Chain 
Send commands, they complete before the Hang Up completes. If a ses- 
sion aborts, a session-ended-abnormally status is returned. If a Chain 
Send time-out expires, the session aborts and a command-timed-out sta- 


*For NcbCallName: bytes 0-1 = NcbLength2, and bytes 2-5 =NcbBuffer2@ in offset: 
segment format. 




244 


Part IV: NetBIOS Technical Reference 


tus is returned. The time-out value for a Chain Send command is deter- 
mined when the session’s Call or Listen completes and cannot be 
specified with this command. 

The total message size must be between zero and 128K-2 bytes inclu- 
sive. If more than one Send or Chain Send is pending within a session, 
the data is transmitted in a first-in, first-out (FIFO) order. If the Chain 
Send cannot be completed for any reason, the session aborts to guaran- 
tee data integrity. 

Chain Send commands without corresponding Receives at the ses- 
sion partner consume NetBIOS resources. It is not advisable to issue 
many Chain Sends without corresponding Receives. 

Chain Sends canceled by a Cancel command terminate their session. 


Delete Name 


31h Wait; Blh No-Wait 

In Out Immediate Return Codes 


NcbCommand 

X 


NcbRetCode 

NcbLsn 

NcbNum 

NcbBuffer® 

NcbLength 

NcbCallName 


X 

NcbName 

NcbRto 

NcbSto 

X 


NcbPost® 

? 


NcbLanaNum 

X 


NcbCmdCplt 


X 

NcbReserve 


? 


OOh 03h 

21h22h23h 

4Xh 

50h-FEh 


Final Return Codes 

OOh 03h OFh 
15h 

21h 22h 23h 
4Xh 

50h-FEh 


The Delete Name command deletes a l6-character name from a NetBIOS 
name table. 

If the Delete Name command is issued when the name has active ses- 
sions, the command completes after deregistering the name. (See the 
Adapter Status command.) The command’s return code has a value of 
OFh, indicating the name has active sessions. 
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In this instance, the actual name deletion is delayed, with the name 
occupying an entry in the adapter’s NetBIOS name table, until all ses- 
sions associated with the name are closed by a Hang Up command’s 
abort. A deregistered name is not usable by subsequent NetBIOS Call and 
Listen commands. Send and Receive commands for existing sessions 
continue to work until the sessions end but datagram commands cannot 
use the name. 

If the name has only pending nonactive session commands when the 
Delete Name command is issued, the name is removed and the com- 
mand-completed status is returned to the user. The pending nonactive 
session commands terminate immediately with the-name-was-deleted 
(17h) status. 

Nonactive session commands are: 

• Listen 

• Receive-Any 

• Receive Datagram 

• Receive Broadcast Datagram 


Hang Up 


12h Wait; 92h No-Wait 


In Out 


NcbCommand 

X 


NcbRetCode 


X 

NcbLsn 

NcbNum 

NcbBuffer® 

NcbLength 

NcbCallName 

NcbName 

NcbRto 

NcbSto 

X 


NcbPost® 



NcbLanaNum 

X 


NcbCmdCplt 


X 

NcbReserve 


p 


Immediate Return Codes 

OOh 03h 
21h 22h 23h 
4Xh 

50h-FEh 


Final Return Codes 

OOh 03h 05h 08h OAh OBh 
18h 

21h22h23h 

4Xh 

50h-FEh 
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The Hang Up command closes the session specified by the NcbLsn 
value. 

When the session closes normally, a good- return status returns. A ses- 
sion-closed status or an illegal session number returns if the session does 
not exist (is already closed or never existed). 

All local pending Receive commands for the session terminate and 
return with session-closed status in the NcbRetCode field when a Hang 
Up command is issued. They terminate whether they have received any 
data. 

If local Send or Chain Send commands are pending for the session, 
the Hang Up command delays until the Send or Chain Send commands 
complete. This delay occurs whether the commands are transferring 
data or are waiting for the remote side to issue Receive or Receive-Any 
commands. The Hang Up completes when any of the following condi- 
tions occur: 

1 . The Send or Chain Send completes. 

2. The Send or Chain Send aborts. 

3. The Send or Chain Send fails because the session terminated in 
response to a Hang Up command issued by the other application. 

4. The Send or Chain Send fails because the time-out specified at ses- 
sion creation expired. 

If one of these conditions does not occur within the system time-out pe- 
riod after the Hang Up command is issued, the Hang Up command re- 
turns with a command-timed-out status and the session aborts. The 
system time-out is calculated by multiplying the system interval and sys- 
tem retry count. The values are NetBIOS constants that are determined 
by the config.sys DXMTOMOD.SYS TRANSMIT. TIMEOUT and TRANS- 
MIT.COUNT parameters, respectively. When the session aborts, all pend- 
ing commands on that session return to the issuer with session-ended- 
abnormally status. 

When the session closes, all Send, Chain Send, and Receive com- 
mands pending on the terminated session return with a session-closed 
status. If a single Receive-Any command is pending on the local name 
used by the session, it returns with a session-closed status. However, if 
multiple Receive-Any commands are pending, only one returns with a 
session-closed status. 

Note that just one (of possibly many) Receive-Any commands pend- 
ing on the session returns, though all Send, Chain Send, and Receive 
commands pending on the session return. 
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When a session terminates, all remote pending commands on that 
session return to the issuer with a session-closed status. 


Listen 


llh Wait; 91h No-Wait 


In Out 


NcbCommand 

X 


NcbRetCode 


X 

NcbLsn 


X 

NcbNum 



NcbBuffer® 



NcbLength 



NcbCallName* 

X 

X 

NcbName 

X 


NcbRto 

X 


NcbSto 

X 


NcbPost® 

? 


NcbLanaNum 

X 


NcbCmdCplt 


X 

NcbReserve 


? 


Immediate Return Codes 

OOh 03h 
21h 22h 23h 
4Xh 

50h-FEh 


Final Return Codes 

OOh 03h 09h OBh 
llh 15h 17h 18h 19h 
21h22h23h 
4Xh 

50h-FEh 


The Listen command opens a session with the name specified in the Ncb- 
CallName field, using the local name specified by the NcbName field. 

If the first position of the NcbCallName field is an asterisk (*), a session 
is established with any network adapter that issues a Call to the local name. 
The name making the Call is returned in the NcbCallName field. A Listen 
command for a specific name has priority over a Listen for any name. 

Sessions may be established with either a local or remote name. Mul- 
tiple sessions may be established with the same pair of names. All Send 
and Chain Send commands, but not their No-Ack variants, for a session 
that are unsuccessful after the specified time-out interval specified by the 
Listen command’s NcbSto field value abort the session. If a Send or 
Chain Send command is canceled by a subsequent Cancel command, the 
session aborts. 


* NetBIOS returns the NcbCallName field if the application specifies an asterisk (*) as 
the first character of the NcbCallName field. 
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Time-out intervals are specified in 1/2 second intervals. A value of zero 
means that no time-out occurs. A Listen command does not time-out, but 
occupies a session entry and is reported as a pending session by Adapter 
Status commands. NetBIOS assigns the LSN value in an incremental, mod- 
ulo 255, roundrobin manner. The values zero and 255 are never assigned. 
The LSN value must be between 1 and 254 (FEh) inclusive. 

The name-conflict-detected error returns if, during the completion 
of a Listen command, a unique name exists in more than one table. All 
adapters with the name registered, except the one where the Call com- 
mand returns successfully, report the name-conflict-detected error.* 


Receive 


In Out 


NcbCommand 

X 


NcbRetCode 


X 

NcbLsn 

X 


NcbNum 



NcbBuffer® 

X 


NcbLength 

X 

X 

NcbCallName 



NcbName 



NcbRto 



NcbSto 



NcbPost® 



NcbLanaNum 

X 


NcbCmdCplt 


X 

NcbReserve 


? 


15h Wait; 95h No-Wait 

Immediate Return Codes 

OOh 03h 
21h 22h 23h 
4Xh 

50h-FEh 


Final Return Codes 

OOh 03h 05h 06h 07h 08h OAh OBh 
18h 

21h 22h 23h 
4Xh 

50h-FEh 


The Receive command receives data from a specified session partner that 
Sends or Chain Sends data on the session. A Receive command cannot 
detect that data may have been sent to it by a Send No-Ack or Chain Send 
No-Ack versus a Send or Chain Send command, respectively. 

If more than one command that can receive data on a specific session 
is pending, they are processed in the following priority: 


1. Receive 
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2 . Receive -Any-for- a-Specified-Name 

3 . Receive-Any-for-Any-Name 

Once the commands are sorted by priority, they are processed in a first- 
in, first-out order within a priority. The Receive time-out value is specified 
with the session Call or Listen command and cannot be specified with this 
command. Use the wait option with this command with care because all 
application processing stops until the command completes. 

When a session closes, either by a local Hang Up command or by the 
remote Hang Up command, all Receives pending for the session return 
with a session closed status. 

If the Receive buffer is not targe enough for the message being re- 
ceived, a message-incomplete status (06h) is returned. To obtain the rest of 
the information before a Send time-out occurs at the other side of the ses- 
sion, the local application should issue another Receive or Receive-Any 
command. However, if the data was sent with a Send No-Ack or Chain 
Send No-Ack, the data is lost already, though the session continues. 


Receive-Any 


I6h Wait; 96h No-Wait 


In Out 


NcbCommand 

X 


NcbRefCode 


X 

NcbLsn 


X 

NcbNum* 

X 

p 

NcbBuffer® 

X 


NcbLength 

X 

X 

NcbCallName 



NcbName 



NcbRto 



NcbSto 



NcbPost® 

? 


NcbLanaNum 

X 


NcbCmdCplt 


X 

NcbReserve 


? 


Immediate Return Codes 

OOh 03h 

21h22h23h 

4Xh 

50h-FEh 


Final Return Codes 

OOh 03h 06h 07h OAh OBh 
13h 17h 18h 19h 
21h 22h 23h 
4Xh 

50h-FEh 


*NcbNum = FFh = Receive-Any-for-Any-Name. 
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The Receive-Any command receives data from any session partner that 
Sends or Chain Sends data on a session associated with a specified local 
name. A Receive-Any command cannot detect that data may have been 
sent to it by a Send No-Ack or Chain Send No-Ack command versus a 
Send or Chain Send command, respectively. The local application speci- 
fies the local name with the name’s NcbNum when issuing this com- 
mand. If the application program sets NcbNum field to FFh, the Receive 
is for any remote name the adapter has a session with, for any of its 
names. This is referred to as a Receive- Any-for-Any-Name command. 

If more than one command that can receive data on a specific session 
is pending, they are processed in the following priority: 

1. Receive 

2 . Receive-Any-for-a-Specified-Name 

3 . Receive-Any-for-Any-Name 

Once the commands are sorted by priority, they are processed in a 
first-in, first-out order. When the return code is presented, NetBIOS sets 
the NcbNum field to the number of the name for which the data was re- 
ceived. The Receive time-out value is specified with the session’s Call or 
Listen command and cannot be specified with this command. 

When a session terminates by a Hang Up command (session-abort), 
one Receive-Any or Receive-Any-for-Any-Name returns with session- 
closed (aborted) status, regardless of the number that may be pending. 
The NcbLsn field of the returning command contains the terminating 
session number. A Receive-Any-for-Any-Name returns only if no Receive- 
Any is pending for the terminating session. 

If the Receive buffer is not large enough for the message being re- 
ceived, a message-incomplete status (06h) is returned. To obtain the rest 
of the information before a Send time-out occurs at the other side of the 
session, the local application should issue another Receive or Receive- 
Any command. However, if the data was sent with a Send No-Ack or 
Chain Send No-Ack, the data is lost already, but the session continues. 

Application programs should use the Receive-Any-for-Any-Name 
command with caution because it may receive messages for other pro- 
grams running in the workstation. Use the wait option with this com- 
mand with care because all application processing stops until the 
command completes. 
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Receive Broadcast Datagram 


23h Wait; A3h No-Wait 


In Out 


NcbCommand 

X 


NcbRetCode 


X 

NcbLsn 



NcbNum 

X 


NcbBuffer® 

X 


Neb Length 

X 

X 

NcbCallName 


X 

NcbName 



NebRto 



NebSto 



NebPost® 

p 


NebLanaNum 

X 


NcbCmdCplt 


X 

NebReserve 

1 

1 

? 


Immediate Return Codes 

OOh 03h 
21h 22h 23h 
4Xh 

50h-FEh 


Final Return Codes 

OOh 03h 06h OBh 
13h 17h 19h 
21h22h23h 
4Xh 

50h-FEh 


The Receive Broadcast command receives a datagram message from any 
adapter issuing a Send Broadcast Datagram. 

There is no time-out associated with this command. A message-in- 
complete status (06h) returns if the receive buffer is not large enough to 
receive all the data, and the remaining data is lost. Use the wait option 
with this command with care because all application processing stops 
until the datagram is received. 
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Receive Datagram 


21h Wait; Alh No-Wait 


In Out 


NcbCommand 

X 


NcbRetCode 


X 

NcbLsn 



NcbNum* 

X 


NcbBuffer® 

X 


NcbLength 

X 

X 

NcbCallName 


X 

NcbName 



NcbRto 



NcbSto 



NcbPost® 

? 


NcbLanaNum 

X 


NcbCmdCplt 


X 

NcbReserve 


? 


Immediate Return Codes 

OOh 03h 
21h 22h 23h 
4Xh 

50h-FEh 


Final Return Codes 

OOh 03h 06h OBh 
13h 17h 19h 
21h22h23h 
4Xh 

50h-FEh 


The Receive Datagram command receives datagrams directed to the local 
name associated with the value in the NcbNum field. Any network name 
can transmit the datagram and the local name can be a unique (including 
the permanent node name) or group name. 

Though this command does not receive broadcast datagrams, if the 
NcbNameNum field contains the value FFh, the command receives a 
datagram directed to any local network name. Receive Datagram com- 
mands for a specific name have priority over a Receive Datagram for any 
name. 

If the local application does not have a Receive Datagram command 
pending when the datagram is transmitted, the message is not received. 
If the receive buffer is not large enough to receive all the data, a message 
incomplete status (06h) returns and the remaining data is discarded. If an 
adapter has several Receive Datagram commands pending for the same 
name, the next Send Datagram command satisfies only one of the Re- 
ceive Datagram commands. 

There is no time-out associated with this command. Use the wait op- 


* NcbNum = FFh = Receive Datagram for any name. 
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tion with care because all application processing stops until a datagram is 
received. 


Reset 


32h Wait 


In Out 


Final Return Codes 


NcbCommand 

NcbRetCode 

NcbLsn 

NcbNum 

NcbBuffer® 

NcbLength 

NcbCallName 

NcbName 

NcbRto 

NcbSto 

NcbPost® 

NcbLanaNum 

NcbCmdCplt 

NcbReserve 


X 

X 

X 


X 


X 

X 


? 


OOh 03h 

23h 

4Xh 

50h-FEh 


The Reset command resets the specified adapter by clearing the NetBIOS 
name and session tables and aborting any existing sessions. This also sets 
the next available LSN value and NcbNum value to 01 h and 02h, respec- 
tively. Whether the Reset command closes and reopens the adapter 
depends on the IBM LAN Support Program CLOSE. ON. RESET (CR) 
parameter. If it is specified as NO, then NetBIOS does not close the 
adapter, leaving all existing DLC communication facilities intact. If the 
CLOSE. ON. RESET parameter is specified as YES, then the adapter is 
closed and reopened, aborting existing DLC communication. 

In either case, if the RESET. VALUES parameter is specified as YES: 

• When the number of sessions specified in the NcbLsn is zero, the 
default maximum number of sessions is the IBM LAN Support 
Program SESSIONS parameter rather than the normal default 
value of 6. 

• When the number of commands specified in the NcbNum field is 
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zero, the default maximum number of pending commands is the 
IBM LAN Support Program COMMANDS value rather than the 
normal default value of 12 . 

Otherwise, the RESET.VALUES parameter is specified as NO and the 
adapter is reset with the maximum number of sessions specified by the 
lesser of the NcbLsn field value and the SESSIONS parameter. This maxi- 
mum is specified by the lesser of the NcbNum field value and the COM- 
MANDS parameter. Note that the network traffic and statistics are reset 
for Token-Ring Adapters, but not for PC Network Adapters. 


Send 

Send No-Ack 


In Out 


NcbCommand 

X 


NcbRetCode 


X 

NcbLsn 

X 


NcbNum 



NcbBuffer® 

X 


NcbLength 

X 


NcbCallName 



NcbName 



NcbRto 



NcbSto 



NcbPost® 

? 


NcbLanaNum 

X 


NcbCmdCplt 


X 

NcbReserve 


? 


I4h Wait; 94h No- Wait 
71h Wait; Flh No-Wait 

Immediate Return Codes 

OOh 03h 
21h 22h 23h 
4Xh 

50h-FEh 


Final Return Codes 

OOh 03h 05h 07h 08h OAh OBh 
18h 

21h 22h 23h 
4Xh 

50h-FEh 


The Send No-Ack command is a variant of the Send command. Its differ- 
ences are explained in Appendix E. 

The Send command sends a message to the session partner specified 
by the LSN value in the NcbLsn field. The NcbBuffer® field points at the 
data to send. 

When the remote side closes a session with a Hang Up command, all 
local Send commands pending for the closed session complete with a 
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session-closed status. If a local Hang Up command is issued with any 
pending Send commands, the Send commands complete before the 
Hang Up command completes. If a session aborts, a session-ended- 
abnormally status returns. 

If the Send time-out expires, the session aborts and a command- 
timed-out status returns. The time-out value for a Send command is de- 
termined when the session’s Call or Listen completes and cannot be 
specified with this command. The message size must be between zero 
and 65,535 (64K-1) bytes inclusive. 

If more than one Send or Chain Send is pending for a session, the 
data is transmitted in a first-in, first-out order within the session. If the 
Send does not complete for any reason, the session aborts to guarantee 
data integrity. 

Send commands without corresponding Receives at the session part- 
ner consume NetBIOS resources. It is not advisable to issue many Sends 
without corresponding Receives. 

Sends canceled by a Cancel command terminate their session. 


Send Broadcast Datagram 


22h Wait; A2h No-Wait 


In Out 


NcbCommand 

X 


NcbRetCode 


X 

NcbLsn 



NcbNum 

X 


NcbBuffer® 

X 


NcbLength 

X 


NcbCallName 



NcbName 



NcbRto 

! 


NcbSto 



NcbPost® 

? 


NcbLanaNum 

X 


NcbCmdCplt 


X 

NcbReserve 




Immediate Return Codes 

OOh 03h 
21h 22h 23h 
4Xh 

50h-FEh 


Final Return Codes 

OOh 01 h 03h 
13h 19h 
21h22h23h 
4Xh 

50h-FEh 
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The Send Broadcast Datagram command sends a datagram message to 
every network adapter. 

Remote adapters not having a Receive Broadcast Datagram command 
pending do not receive the message. If an adapter issues a Send Broad- 
cast Datagram and has a Receive Broadcast Datagram pending, the 
adapter receives its own message. If an adapter has several Receive 
Broadcast Datagram commands pending, the next Send Broadcast 
Datagram command satisfies all Receive Broadcast Datagram commands. 


Send Datagram 


20h Wait; AOh No-Wait 


In Out 


NcbCommand 

X 


NcbRetCode 


X 

NcbLsn 



NcbNum 

X 


NcbBuffer® 

X 


NcbLength 

X 


NcbCallName 

X 


NcbName 



NcbRto 



NcbSto 



NcbPost® 

? 


NcbLanaNum 

X 


NcbCmdCplt 


X 

NcbReserve 


? 


Immediate Return Codes 

OOh 03h 

21h22h23h 

4Xh 

50h-FEh 


Final Return Codes 

OOh 01 h 03h 
13h 19h 
21h 22h 23h 
4Xh 

50h-FEh 


The Send Datagram command sends datagrams to specified network 
names. The specified name may be a unique (including a permanent 
node name) or group name. 

Adapters having the name but not having a pending Receive Datagram 
command for that name discard the datagram. If an adapter has a Receive 
Datagram pending for a name and issues a Send Datagram for that name, 
the adapter receives its own message. The Send Datagram command satis- 
fies only one pending Receive Datagram command if an adapter has sev- 
eral Receive Datagram commands pending for the same name. 
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Session Status 


34h Wait; B4h No-Wait 


In Out 


NcbCommand 


X 

NcbRetCode 


X 

NcbLsn 



NcbNum 


X 

NcbBuffer® 

X 


NcbLength 

X 


NcbCallName 



NcbName 

X 


NcbRto 



NcbSto 



NcbPost® 



NcbLanaNum 

X 


NcbCmdCplt 


X 

NcbReserve 


? 


Immediate Return Codes 

OOh 03h 
21h 22h 23h 
4Xh 

50h-FEh 


Final Return Codes 

OOh 01 h 03h 06h 
15h 19h 
21h 22h 23h 
4Xh 

50h-FEh 


The Session Status command obtains the status of one or all sessions as- 
sociated with a local name. If an asterisk (*) is specified as the first byte of 
the NcbName field, this command obtains the status for all of the names 
in the NetBIOS name table. 

The minimum valid buffer length is 4 bytes. An illegal buffer length 
status (01 h) is returned if the NcbLength field is less than 4. A message 
incomplete status (06h) is returned if the NcbLength field is less than the 
generated status data. To obtain all status data, the buffer length must be 
at least 4 plus 36 times the number of reported sessions. 

A remote Adapter Status command fails if it is not successful before 
the system time-out expires. The system time-out is calculated by multi- 
plying the system interval and system retry count. The values are Net- 
BIOS constants that are determined by the config.sys DXMTOMOD.SYS 
TRANSMIT. TIMEOUT and TRANSMIT.COUNT parameters, respectively. 
The returned data has the format outlined in Table 20-3. 

If adequate buffer space is available, the contents of bytes 4-39 are 
repeated for every session associated with the specified name (36 bytes 
for each session). Otherwise, the excess data is lost. 

The session state field has the following values; 
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01 h; Listen pending 

02 h; Call pending 
03h: Session established 
04h: Hang Up pending 
05h: Hang Up complete 
06h: Session aborted 


Ikble 20-3. Returned Data Format 


Offset 

Length 

MASM 

C 

Field Contents 

00 OOh 

1 

DB 

USGC 

Name Number for reported sessions 

01 01 h 

1 

DB 

USGC 

Number of sessions associated with this 





name 

02 02h 

1 

DB 

USGC 

Number of pending Receive Datagram 
and Receive Broadcast Datagram 
commands 

03 03h 

1 

DB 

USGC 

Number of pending Receive-Any 
commands 

04 04h 

1 

DB 

USGC 

Local Session Number 

05 05h 

1 

DB 

USGC 

Session state 

06 06h 

16 

DB 

char[ ] 

Local name 

22 I6h 

16 

DB 

char[ ] 

Remote name 

38 26h 

1 

DB 

USGC 

Number of pending Receive commands 

39 27h 

1 ‘ 

DB 

USGC 

Number of pending Send and Chain 

Send commands 
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Unlink 


70h Wait 


In Out Final Return Codes 


NcbCommand 

NcbRetCode 

NcbLsn 

NcbNum 

NcbBuffer® 

NcbLength 

NcbCallName 

NcbName 

NcbRto 

NcbSto 

NcbPost® 

NcbLanaNum 

NcbCmdCplt 

NcbReserve 


X 

X 

X 

X 


? 


OOh 03h 
21h 22h 23h 
4Xh 

50h-FEh 


The Unlink command provides compatibility with the original PC Net- 
work LANA NetBIOS which uses the Unlink command to disconnect 
from an RPL server. 

OOh is the only valid NcbLanaNum value for an Unlink command. A 
value of 01 h may appear to be accepted, but only because NetBIOS does 
not inadvertently reject the value during processing. 

If the Unlink command is for an original PC Network LANA adapter 
and RPL is active, NetBIOS subsequently issues an internal Hang Up 
command with a wait option using an internal Neb located in high mem- 
ory. This Neb contains a value of OOh in its NcbLanaNum field because 
NetBIOS RPL activities use the primary adapter exclusively. 

Alternatively, the adapter may not be an original PC Network LANA 
adapter or an original PC Network LANA adapter with RPL active. In this 
case, NetBIOS does not execute a Hang Up command for an RPL session, 
but treats the command as a no-operation and simply returns a good-re- 
turn code. In any instance, OOh virtually always returns as the return code 
for any Hang Up command that specifies a valid NcbLanaNum field value. 
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Special Value Summary 

NetBIOS treats four values as special values. Their NetBIOS meaning var- 
ies by the context of their use. 


Special Value OOh 

OOh is invalid as a first character of any name except a permanent node 
name. 

OOh is an invalid NcbLsn value. 

OOh is an invalid NcbNameNum value. 

Using OOh in a Call or Listen command’s NcbRto field indicates ses- 
sion Receive and Receive-Any commands should not time-out. 

Using OOh in a Call or Listen command’s NcbSto field indicates that 
session Send and Chain Send commands should not time-out. 

Using OOh in the NcbLsn and NcbNum fields for a Reset Command 
indicates NetBIOS should determine the maximum number of allowable 
simultaneously existing sessions and pending control blocks, respectively. 

OOh is the only valid NcbLanaNum value for an Unlink command. A 
value of 01 h may appear to be accepted, but only because NetBIOS does 
not inadvertently reject the value during processing. 


Special Value 01 h 

NetBIOS reserves 01 h for the permanent node name NetBIOS name 
number. The permanent node name is always used in NetBIOS commu- 
nication even if the value is overridden for use as a LAN address. 

For the original PC Network LANA adapter, the RPL session always 
has an LSN value of Olh because it is always the first NetBIOS session. 


Special Value FFh 


FFh is an invalid NcbLsn value. 

FFh is an invalid NcbNameNum value. 

Using FFh as the NcbNum value in a Receive-Any command specifies 
the command is a Receive-Any-for-Any-Name command. 

Using FFh as the NcbNum value in a Receive Datagram command 
specifies the command can receive a datagram directed to any local name. 
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Special Value * 

Using an asterisk (*) as the first character of a Listen command’s Ncb- 
CallName field indicates that any adapter calling the name specified in 
the Listen’s NcbName field is a valid session partner. 

Using * as the first character of an Adapter Status command’s Ncb- 
CallName field indicates the status request is for the local adapter speci- 
fied by the NcbLanaNum field value. 

Using * as the first character of a Session Status command’s Ncb- 
CallName field indicates the status request is for all names in the local 
adapter specified by the NcbLanaNum field value. 


Complex Hang Up Scenario 

Assume two workstations are conducting a communication session. As- 
sume further that each station has two Receive commands, two Receive- 
Any commands, a Chain Send command and a Send command pending 
on their respective side of the session. Finally, assume that one station, 
station XXX, issues a Hang Up command specifying the given session. The 
following discussion illustrates the various outcomes of this situation. 

First, all Receive commands for the session at station XXX are imme- 
diately completed with a session-closed NcbRetCode, but only one of 
the Receive-Any commands is completed with a session-closed NcbRet- 
Code. The absence of these pending commands may cause pending 
Send and Chain Send commands to time-out on the other side of the ses- 
sion, immediately aborting the session. 

Alternatively, the Hang Up command is delayed at station XXX until 
the local pending Send and Chain Send commands complete. In the 
event they do not complete before the system time-out period expires, 
the Hang Up command itself times-out and the session is aborted. The 
system time-out period is computed by multiplying the system interval 
and system retry count. The values are NetBIOS constants that are deter- 
mined by the config.sys DXMTOMOD.SYS TRANSMIT. TIMEOUT and 
TRANSMIT.COUNT parameters, respectively. 


Return Code Summary 

For wait option commands, the AL register contains the final command 
return code. Alternatively, for no- wait option commands, the AL register 



262 


Part IV: NetBIOS Technical Reference 


contains the immediate return code. If the return code is not OOh, then 
no further processing is done on the command. Finally, the AL register 
provides the final return code to the post routine if the command is ini- 
tially accepted and specifies a post routine. 

The NcbRetCode Field contains the final return code for commands 
that specify the wait option or the no- wait option without a post routine. 

The NcbCmdCplt Field contains the final return code if a no- wait 
command option is used with an accepted command that does not spec- 
ify a post routine. 
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NetBI0S2.h Listing 


#define TRUE 1 
#define FALSE 0 

^define SUCCESS 1 
^define FAILURE 0 

dfifndef US6C 

#define USGC unsigned char 
Send if 

Sifndef USGI 

Sdefine USGI unsigned 

Sendif 

Sifndef USGL 

Sdefine USGL unsigned Long 
Send if 

Sdefine NetbiosInt21FunctionCode ((USGC) 0x2A) 

Sdefine NetbiosIntSC ((USGC) 0x50 

Sdefine COMMANO_PENDING ((USGC) OxFF) 

Sdefine Mcb Neb 

Sdefine MAX_ADAPTER_NUMBER 1 

Sdefine MAX_SESSION_COUNT 254 

Sdefine MAX_NAMES 254 

Sdefine MAX_COMMAND_COUNT 255 


265 
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#def ine 

NO_WAIT 


((USGC) 

0x80) 

#define 

NETBIOS. 

_RESET_WAIT_ONLY 

((USGC) 

0x32) 

#def ine 

NETBIOS 

_CANCEL_WAIT_ONLY 

((USGC) 

0x35) 

#def ine 

NETBIOS 

_ADAPTER_STATUS 

((USGC) 

0x33) 

#def ine 

NETBIOS 

_UNLINK^WAIT^ONLY 

((USGC) 

0x70) 

#def ine 

NETBIOS 

JRACE 

((USGC) 

0x79) 

#def ine 

NETBIOS 

_ADD_NAME 

((USGC) 

0x30) 

#def ine 

NETBIOS 

_ADD_GROUP^NAME 

((USGC) 

0x36) 

#def ine 

NETBIOS 

_DELETE_NAME 

((USGC) 

0x31) 

#def ine 

NETBIOS 

JIND_NAME 

((USGC) 

0x78) 

^define 

NETBIOS 

_CALL 

((USGC) 

0x10) 

#def ine 

NETBIOS 

_LISTEN 

((USGC) 

0x11) 

#def ine 

NETBIOS 

..HANG_UP 

((USGC) 

0x12) 

/(define 

NETBIOS 

.SEND 

((USGC) 

0x14) 

/(define 

NETBIOS 

_SEND_NO_ACK 

((USGC) 

0x71) 

/(define 

NETBIOS 

_CHAIN_SEND 

((USGC) 

0x17) 

/(define 

NETBIOS 

_CHAIN_SENDJ0_ACK 

((USGC) 

0x72) 

/(define 

NETBIOS 

.RECEIVE 

((USGC) 

0x15) 

/(define 

NETBIOS 

.RECEIVE..ANY 

((USGC) 

0x16) 

#def ine 

NETBIOS 

.SESSION^STATUS 

((USGC) 

0x34) 

#def ine 

NETBIOS 

.SEND..DATAGRAM 

((USGC) 

0x20) 

#define 

NETBIOS 

_RECEIVE_DATAGRAM 

((USGC) 

0x21) 

#def ine 

NETBIOS 

.SEND_BDATAGRAM 

((USGC) 

0x22) 

/(define 

NETBIOS 

.RECEIVE_BDATAGRAM 

((USGC) 

0x23) 

/(define 

NETBIOS 

INVALID COMMAND 

((USGC) 

0x7F) 


/* LAN Adapter Types */ 

^define TOKEN_RING_ADAPTER ((USGC) OxFF) 
^define PC_NETWORK_ADAPTER ((USGC) OxFE) 

/* NETBIOS Version Numbers */ 

^define VERSION_MASK ((USGC) OxOF) 

#define PARM_MASK ((USGC) OxFO) 

Sdefine OLD_PARMS ((USGC) 0x10) 

Sdefine NEW_PARMS ((USGC) 0x20) 
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struct Neb 
{ 


USGC 

NebCommand; 

/* 

command code 

*/ 


USGC 

NebRetCode; 

/* 

return code 

*/ 


USGC 

NcbLsn; 

/* 

local session number 

*/ 


USGC 

NebNum; 

/* 

Datagram ADD NAME table entry 

*/ 


char 

* NebBuf ferOffset; 

/* 

I/O buffer offset 

*/ 


USGI 

NebBufferSegment; 

/* 

I/O buffer segment 

*/ 


USGI 

NcbLength; 

/* 

length of data in I/O buffer 

+/ 


char 

NebCal lName[16] ; 

/* 

remote system name for CALL 

*/ 


char 

NcbName[16]; 

/* 

local adapter network name 

*1 


USGC 

NebRto; 

/* 

receive timeouts in 1/2 second 

uni ts 

*/ 

USGC 

NebSto; 

/* 

send timeouts in 1/2 second 

units 

*/ 

char 

* NebPostRtnOffset; 

/* 

offset of post routine 

*/ 


USGI 

NcbPostRtnSegment ; 

/* 

segment of post routine 

★/ 



USGC NebLanaNum; /* network adapter number to execute cmd */ 
USGC NcbCmdCplt; /* OxFF ==> command pending, else empLted */ 

char NebReservedAreaCH]; /* work area for network card */ 

> ZeroNcb; /* prototype NCB for sizeof calcs */ 


^define MIN_NAME_NUM 2 

#define MAX_NAME_NUM 254 
#define ILLEGAL_NAME_NUM 0 

^define MIN_LSN 1 

#define MAX^LSN 254 
#define ILLEGAL_LSN 0 

struct NameTableEntry i 

char EntryNameC163 ; 
USGC EntryNameNum; 
USGC EntryNameStatus 
>; 


/* symbolic network name ★/ 
/* associated name number */ 
/* & with 0x0087 for status */ 


struct DlcStatus *C 

/★ +00 */ USGC PermanentNodeNameC6] ; 

/* +06 */ USGC MajorVersionNumber; /* low-order nibble only */ 
/* +07 */ USGC AlwaysZero; 
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/* 

+08 

*/ 

USGC 

LanAdapterType; 

/* 

+09 

*/ 

US6C 

MinorVersionNumber; 

/* 

+10 

*/ 

USGI 

Report ingPeriodMi nut es; 

/* 

+12 

*/ 

USGI 

F rameRe j ectedRecei veCount ; 

/* 

+14 

*/ 

USGI 

F rameRe j ectedXmi t Count ; 

/* 

+16 

*/ 

USGI 

I^FrameRecei veErrorCount ; 

/* 

+18 

★/ 

USGI 

XmitAbortCount; 

/★ 

+20 

*/ 

USGL 

SuccessfuLFrameXmit Count; 

/* 

+24 

*/ 

USGL 

Successful FrameRcvCount; 

/★ 

+28 

★/ 

USGI 

I_FrameXmitErrorCount; 

/* 

+30 

+/ 

USGI 

RmtRqstBufferDep let ionCount ; 

/* 

+32 

*/ 

USGI 

Expi redTITimerCount; 

/* 

+34 

*/ 

USGI 

Expi redTITimerCount; 

1* 

+36 

*/ 

struct LocaLTrAdapterStatus far * LocalExtStatPti 

/* 

+40 

★/ 

USGI 

FreeCommandB locks; 

/* 

+42 

*/ 

USGI 

CurrentMaxNcbs; 

/* 

+44 

*/ 

USGI 

MaximumCommands; 

/* 

+46 

*/ 

USGI Transmi t Buff erOep let ionCount; 

/* 

+48 

*/ 

USGI 

MaximumDatagramPacketSize; 

/* 

+50 

*/ 

USGI 

PendingSess ionCount; 

/* 

+52 

*/ 

USGI 

MaxPendi ngSess i onCount ; 

/* 

+54 

★/ 

USGI 

MaximumSessions; 

/* 

+56 

*/ 

USGI 

MaximumSessionPacketSi ze; 

/* 

+58 

+/ 

USGI NameTableEntryCount; 

/* 

+60 

*/ 

struct NameTableEntry TabLeEntry[MAX__NAMES] ; 

> ; 

struct 

LocaLTrAdapterStatus { 

/* 

+00 

*/ 

USGI 

Di rInitBringUpErrorCode; 

/* 

+02 

*/ 

USGI 

Di rOpenAdapterErrorCode; 

/★ 

+04 

*/ 

USGI 

LatestRingStatus; 

/* 

+06 

*/ 

USGI 

LatestAdapterCheckReasonCode; 

/* 

+08 

*/ 

USGI 

LatestPcDetectedErrorCode; 

/* 

+10 

*/ 

USGC 

LatestOperationalErrorCode; 

/* 

+11 

*/ 

USGC 

Latest ImplicitCcbReturnCode; 

/* 

+12 

*/ 

USGI 

Adapt er Li neErrors; 

/* 

+14 

*/ 

USGI 

Adapt er Interna lErrors; 

/* 

+16 

*/ 

USGI 

Adapt erBurst Errors; 

/* 

+18 

★/ 

USGI 

AdapterAcError; 

/* 

+20 

*/ 

USGI 

Adapt erAbort Deli mi ter; 

/* 

+22 

*/ 

USGI 

AdapterReservedI ; 

/* 

+24 

*/ 

USGI 

AdapterLostFrame; 

/* 

+26 

*/ 

USGI 

AdapterRecei veCongest i on; 

/* 

+28 

*/ 

USGI 

AdapterFrameCopi edErrors; 

/* 

+30 

*/ 

USGI 

Adapt erFrequencyErrors; 
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/* 

+32 

★/ 

USGI 

Adapt erTokenErrors; 

/* 

+34 

*/ 

USGI 

AdapterReserved2; 

/* 

+36 

*/ 

USGI 

AdapterReserved3; 

/* 

+38 

*/ 

USGI 

>; 

Adapt erReserved4; 

struct 

LanaStatus { 


/* 

+00 

*/ 

USGC 

PermanentNodeName[6] ; 

/* 

+06 

*/ 

USGC 

Externa LJumperSetting; 

/* 

+07 

+/ 

USGC 

SelfTestResuLts; 

/* 

+08 

+/ 

USGC 

SoftwareVersionMajor; 

/* 

+09 

*/ 

USGC 

SoftwareVersionMinor; 

/* 

+10 

*/ 

USGI 

Report i ngPer i odMi nut es ; 

/* 

+12 

*/ 

USGI 

CrcErrorCount; 

/* 

+14 

*/ 

USGI 

ALignmentErrors; 

/* 

+16 

*/ 

USGI 

Col li sionCount; 

/* 

+18 

*/ 

USGI 

Xmi tAbortCount; 

/* 

+20 

*/ 

USGL 

SuccessfulXmi ts; 

/* 

+24 

*/ 

USGL 

SuccessfulRcvs; 

/* 

+28 

+/ 

USGI 

Retransmi tCount; 

/* 

+30 

★/ 

USGI 

ResourceDepLetionCount; 

/* 

+32 

*/ 

char 

ReservedAreal [83 ; 

/* 

+40 

+/ 

USGI 

FreeCommandB locks ; 

/* 

+42 

*/ 

USGI 

CurrentMaxNcbs; 

/* 

+44 

*/ 

USGI 

HwMaxCommandB locks; 

/★ 

+46 

*/ 

char 

ReservedArea2[4] ; 

/* 

+50 

*/ 

USGI 

PendingSessionCount; 

/* 

+52 

*/ 

USGI 

CurrentMaxPendingSessions; 

1* 

+54 

*/ 

USGI 

HwMaxSessionCount; 

/* 

+56 

*/ 

USGI 

Maxi mumPacket Size; 

/* 

+58 

*/ 

USGI 

NameTab 1 eEnt ry Count ; 

/* 

+60 

*/ 

struct NameTabLeEntry TabLeEntry[16] 


> ; 


struct DateTimeStruct { USGI DateCX; 

USGI DateDX; 
USGI TimeCX; 
USGI TimeDX; 

>; 


^define NB_ILLEGAL_BUFFER_LENGTH 0x01 
#define NB_INVALID_COMMAND 0x03 
#define NB_COMMAND_TIMED_OUT 0x05 
#define NB_MESSAGE_INCOMPLETE 0x06 
#define NB NO ACK FAILURE 0x07 
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li/define NB_ILLEGAL_LSN 0x08 
define NB_NO_RESOURCE_AVAILABLE 0x09 
#define NB_SESSION_CLOSED OxOA 
#define NB_COMMAND_CANCELED OxOB 
#define NB_DUPLICATE_LOCAL_NAME OxOD 
Sdefine NB_NAME_TABLE_FULL OxOE 
^define NB_NAME_HAS_ACTIVE_SESSIONS OxOF 

^define NB_LOCAL_SESSION_TABLE_FULL 0x11 
^define NB_SESSION_OPEN_REJECTED 0x12 
^define NB_ILLEGAL_NAME_NUMBER 0x13 
^define NB_CANNOT_FIND_CALLED_NAHE 0x14 
#define NB_NAME_NOT_FOUND_OR_ILLEGAL 0x15 
^define NB_NAME_USED_ON_RMT_ADAPTER 0x16 
#define NB_NAME_DELETED 0x17 
Kfdefine NB_SESSION_ENDED_ABNORMALLY 0x18 
^define NB_NAME_CONFLICT_DETECTED 0x19 
#define NB_INCOMPATIBLE_RMT_DEVICE OxIA 

/ifdefine NB_INTERFACE_BUSY 0x21 
#define NB_TOO_MANY_COMMANDS_PENDING 0x22 
#define NB_INVALID_ADAPTER_NUMBER 0x23 
#define NB_CMD_COMPLETEO_DURING_CANCEL 0x24 
#define NB_RESERVED_NAME_SPECIFIED 0x25 
^define NB_CMD_NOT_VALID_TO_CANCEL 0x26 

#define NB_LANA_SYSTEM_ERROR 0x40 
#define NB_LANA_REMOTE_HOT_CARRIER 0x41 
#define NB_LANA_LOCAL_HOT_CARRIER 0x42 
^define NB_LANA_NO_CARRIER_OETECTED 0x43 
#define NB_UNUSUAL_NETWORK_CONDITION 0x44 

#define NB_ADAPTER_MALFUNCTION 0x50 

lYdefine NB_COMMAND_PENDING OxFF 

#define MAX_SESSION_BUFFER_SIZE 8192 
struct SessionMsg < USGL TextLength; 


char Text [MAX_SESSION_BUFFER_SIZE] ; 

>; 
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C Post Routine listing 


#define LINT_AR6S 

#incLude <dos.h> 

#include <stdio.h> 

^include "netbios2.h" 

struct SREGS SegRegs; 

struct Neb DatagramNcb; 

char BufferCI]; 

char CLientName[16] = "WDS-DG"; 

#if defined(LINT_ARGS) 
extern int mainCint argc,char * *argv); 
extern void SendNoWai tDatagram(void) ; 
extern void cdecL interrupt far PostRoutineC 

unsigned int es, unsigned int ds, 
unsigned int di, unsigned int si, 
unsigned int bp, unsigned int sp, 
unsigned int bx, unsigned int dx, 
unsigned int cx, unsigned int ax, 
unsigned int ip, unsigned int cs, 
unsigned int flags); 

extern void NetbiosRequest (struct Neb *NcbPointer) ; 
extern void Logo(void); 

#endi f 

USGC PostRoutineDri ven = FALSE; 
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int mainCargc, argv) 
int argc; 
char *argvC] ; 

LogoO; 

SendNoWai tDatagramO ; 

whi LeCPostRoutineDn’ven == FALSE) 

; /* spins here until PostRoutineDri ven == TRUE */ 

printf (''\n\nThe return code was %02Xh...", 

DatagramNcb.NcbRetCode) ; 

printf ("\n\nProgram ending \n"); 

return 0; 

> 

void SendNoWai tDatagramO 
US6I temp; 

char far * BufferPtrFar = (char far *) Buffer; 

void (far *PostRoutinePtr) O = (void (far *)()) PostRoutine; 

DatagramNcb.NcbCommand = NETBIOS_SEND_DATAGRAM + N0_WAIT; 

DatagramNcb.NcbLength = 1; 

DatagramNcb.NcbBufferOffset = (char *) FP_OFF(BufferPtrFar) ; 
DatagramNcb.NcbBufferSegment = (USGI) FP_SEG(BufferPtrFar) ; 

DatagramNcb.NcbPostRtnOffset = (char *) FP_OFF(PostRoutinePtr) ; 
DatagramNcb.NcbPostRtnSegment = (USGI) FP_SEG(PostRout inePtr) ; 

DatagramNcb.NcbNum = 0x01; /* use Permanent Node Name NameNum */ 

for (temp = 0; temp < 16; temp++) 

DatagramNcb.NcbCal INameCtemp] = CLientNameEtemp] ; 

Netbi osRequest (SDatagramNcb) ; 

> 
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void cdecL interrupt far PostRout i ne(es, ds, di , si, 

bp, sp, bx, dx, 
cx, ax, ip, cs, flags) 

US6I es, ds, di , si, bp, sp, bx, dx, cx, ax, ip, cs, flags; 

PostRoutineDri ven = TRUE; /* no DOS calls allowed!!! */ 

printf("\nNcb SE6:OFF == %04X:%04X", es, bx); /* tsk tsk */ 

> 

void NetbiosRequest (NcbPointer) 
struct Neb *NcbPointer; 

union REGS InRegs, OutRegs; /* defined in dos.h */ 
struct Neb far *NcbPtr = (struct Neb far ★) NcbPointer; 

segreadC&SegRegs) ; 

SegRegs.es = FP_SE6(NcbPtr) ; 

InRegs. x.bx = FP_OFF(NcbPtr) ; 

printf ("\n\nNcb SEGrOFF == %04X:%04X'', SegRegs.es, 

InRegs. x.bx) ; 

int86x(NetbiosInt5C, &InRegs, &OutRegs, &SegRegs); 

> 

void LogoO 
{ 

printf (''\n NetBIOS C Post Routine Sample Program"); 
printf("\n © Copyright 1988 W. David Schwaderer") ; 

> 
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Error Codes, Reasons, and Actions 


Return Code 

Meaning 

OOh 

Successful completion, good return 

01 h 

Invalid buffer length 

03h 

Invalid command 

05h 

Command timed-out 

06h 

Incomplete received message 

07h 

Local No-Ack command failed 

08h 

Invalid Local Session Number 

09h 

No resource available 

OAh 

Session has been closed 

OBh 

Command was canceled 

ODh 

Duplicate name in local NetBIOS name table 

OEh 

NetBIOS name table full 

OFh 

Name has active sessions and is now deregistered 

11 h 

NetBIOS local session table full 

12h 

Session open rejected because no Listen is outstanding 

13h 

Illegal name number 

I4h 

Cannot find name called or no answer 

15h 

Name not found, or cannot specify asterisk (*) or OOh as first byte of 
NcbName, or the name is deregistered and cannot be used 

l6h 

Name in use on remote adapter 

17h 

Name deleted 

18h 

Session ended abnormally 

19h 

Name conflict detected 

lAh 

Incompatible remote device (PC Network) 
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Return Code Meaning 

21 h Interface busy 

22h Too many commands outstanding 

23h Invalid number in NcbLanaNum field 

24h Command completed while cancel occurring 

25h Reserved name specified for Add Group Name 

26h Command not valid to cancel 

3 Oh Name defined by another process (OS/2 Extended Edition only) 

34h NetBIOS environment not defined (OS/2 Extended Edition only) 

35h Required operating system resources exhausted (OS/2 Extended Edition 

only) 

36h Maximum applications exceeded (OS/2 Extended Edition only) 

37h No SAPs available for NetBIOS (OS/2 Extended Edition only) 

38h Requested resources not available (OS/2 Extended Edition only) 

40h System error (PC Network) 

41 h Hot carrier from a remote adapter detected (PC Network) 

42h Hot carrier from this adapter detected (PC Network) 

43h No carrier detected (PC Network) 

4Eh Status bit 12, 14, or 15 on longer than one minute (Token-Ring) 

4Fh One or more of status bits 8-11 on (Token-Ring) 

50h-F6h Adapter malfunction 

F7h Error on implicit DIR.INITIALI2E 

F8h Error on implicit DIR. OPEN. ADAPTER 

F9h IBM LAN Support Program internal error 

FAh Adapter check 

FBh NETBIOS program not loaded in PC 

FCh DIR.OPEN.ADAPTER or DLC. OPEN. SAP failed — check parameters 

FDh Unexpected adapter close 

FFh Command-pending status 


OOh, Successful Completion, Good Return 

Meaning-. The command completed without error. 

Required Action -. No action is required. This is normal after each suc- 
cessful command. 
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01 h, Invalid Buffer Length 

Meaning: A Send Datagram or Send Broadcast Datagram command can- 
not send more than 512 bytes. For Adapter Status and Session Status com- 
mands, the specified buffer length was less than the minimum required. 

Required Action-. Specify the correct size for the buffer and try the 
command again. 


03h, Invalid Command 

Meaning: The command code used is incorrect. 

Required Action: Reissue the correct command code. 


05h, Command Timed-Out 

Meaning: For a Call or an Adapter Status command, the system time-out 
elapsed before the command completed. For Send, Chain Send, or Re- 
ceive commands, the time-out period specified in the Call or Listen com- 
mand establishing the session expired. For a Hang Up command, the time- 
out period expired for an outstanding Send or Chain Send to complete. 

Required Action: For a Call, try again later. For an Adapter Status com- 
mand, use a correct name. For a Send command, the session has been 
aborted. Establish another session, synchronize the session, and reissue the 
Send making sure a receive is outstanding on the other side of the session. 

06h, Incomplete Received Message 

Meaning: Part of a message was received because the specified buffer 
length is not big enough to receive the full message. 

Required Action: For Receive and Receive-Any command: Issue an- 
other Receive to get the rest of the message before the remote side times- 
out, but not if the data was sent using a Send No-Ack or Chain Send No- 
Ack. (It is already discarded.) For Status, Session Status, Receive 
Datagram, and Receive Broadcast Datagram commands, the remaining 
data is lost. 

If the command was a remote Status command, the error occurs 
when the remote side cannot transmit the entire status data because it is 
larger than the maximum-length transmittable Ul-frame. 
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07h, Local No-Ack Command Failed 

Meaning-. One or more Send No-Ack and/or Chain Send No-Ack com- 
mands issued within this workstation for this LSN was unsuccessful. 

Required Action-. The session is still active. Resynch the data flow 
however possible and continue. 


08h, Invalid Local Session Number 

Meaning-. The specified session number is not for an active session. 

Required Action-. Reissue the command specifying an active session 
number. 


09h, No Resource Available 

Meaning-. A session cannot be established with a remote application pro- 
gram because there is no more room in its session table. 

Required Action-. Reissue the command at a later time. 


OAh, Session Has Been Closed 

Meaning-. The session partner closed the session. 
Required Action-. None. 


OBh, Command Was Canceled 

Meaning-. The command was canceled by a Cancel command. 
Required Action-. None. 


ODh, Duplicate Name in Local NetBIOS Name Table 

Meaning-. An Add Name command specified a registered name that is 
currently in the local name table. 

Required Action-. Reissue the command and specify another name or 
use the name without trying to add it. 
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OEh, NetBIOS Name Table Full 

Meaning-. The number of names in the NetBIOS name table already 
equals the value previously specified in the DIR.OPEN. ADAPTER com- 
mand. 

Required Action-. Wait until a name is deleted causing an available 
entry. 

OFh, Name Has Active Sessions and Is Now Deregistered 

Meaning-. The name specified in a Delete Name command is active in a 
session, but is now marked as deregistered. The name is unusable for any 
new sessions though it still active-sessions and occupies a slot in the ta- 
ble. 

Required Action-. Close all the sessions using this name so the name 
can be deleted and its name table slot can be freed. 


llh, NetBIOS Local Session Table Full 

Meaning-. There are no available entries in the local session table. (The 
number of sessions is user-specified in Reset or DIR. OPEN. ADAPTER 
commands.) 

Required Action-. Wait until a session closes making an entry available. 

12h, Session Open Rejected because No Listen Is Outstanding 

Meaning-. No Listen command is pending on the remote NetBIOS Inter- 
face. 

Required Action: Wait until a Listen command is issued at the remote 
NetBIOS Interface. 


13h, Illegal Name Number 

Meaning: The specified name number no longer exists or was never 
specified. 

Required Action: Use the most recent number that was assigned to 
the name. 
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I4h, Cannot Find Name Called or No Answer 

Meaning: No response to the Call command was received. 

Required Action: Try the Call command later. 

15h, Name Not Found 

Meaning: The specified name is not in the NetBIOS name table, or the 
first character of the name is either an ASCII asterisk or 00, or the name is 
deregistered and cannot be used. 

Required Action: Try a valid name. 

I6h, Name in Use on Remote Adapter 

Meaning: The specified name is already registered as a unique name on 
another table. 

Required Action: Specify another name or have the name deleted and 
changed at the other adapter. 

17h, Name Deleted 

Meaning: The name has been deleted and cannot be used. 

Required Action: Add the name to the NetBIOS name table again and 
reissue the command. 

18h, Session Ended Abnormally 

Meaning: A Send command terminated because of a time-out or hard- 
ware problem. 

Required Action: Issue a remote Adapter Status command for the 
other adapter and check your adapter’s cable. Reestablish and synchro- 
nize the new session. 

I 9 I 1 , Name Conflict Detected 

Meaning: Network protocols have detected two or more identical 
unique names on the network. 

Required Action: Remove the identical network names. 
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lAh, Incompatible Remote Device 

Meaning: An unexpected protocol packet has been received. 

Required Action: Verify that all adapters on the network observe the 
network’s protocols. 

21h, Interface Busy 

Meaning: The NetBIOS Interface is either busy or out of local resources. 
This condition can also be caused by having any of the ring status bits 12 , 
14, or 15 on. 

Required Action: Try the command later. 

22h, Too Many Commands Outstanding 

Meaning: The number of commands currently pending equals the maxi- 
mum number allowed. 

Required Action: Try the command later. 

23h, Invalid Number in NcbLanaNum Field 

Meaning: The only valid values for the NcbLanaNum field are 0x00 and 
0x01, or the specified adapter is not present. 

Required Action: Verify that the adapter is present, or correct the 
value and retry the command using 00 for the primary adapter and 01 for 
the alternate adapter. 

24h, Command Completed while Cancel Occurring 

Meaning: A command completed that was in the process of being can- 
celed by a Cancel command. 

Required Action: None. 

2 5h, Reserved Name Specified for Add Group Name 

Meaning: An Add Name or Add Group Name command specified an IBM 
reserved name. 

Required Action: Undocumented. 
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26h, Command Not Valid to Cancel 

Meaning-. The command specified in a Cancel command is not valid to 
cancel. 

Required Action-. Verify the correctness of the cancel command. 

30h, Name Defined by Another Process (OS/2 Extended Edition 
only) 

Meaning-. The command refers to a locally defined NetBIOS name. Re- 
sources reserved for a given process within the workstation can only be 
used by that process and the specified local NetBIOS name is already re- 
served for another process. 

Required action-. Use another name or remove the process using the 
specified name. 


34h, NetBIOS Environment Not Defined (OS/2 Extended Edition 
only) 


Meaning-. The Reset command must be the first command issued by a 
process. This return code value does not apply to the Reset command. 
Required action-. Issue the Reset command. 


35h, Required Operating System Resources Exhausted (OS/2 
Extended Edition only) 

Meaning-. NetBIOS cannot initiate the requested command because OS/ 
2 Extended Edition resources are not available to support the command. 
This return code does not apply to the Reset command. 

Required action: Retry later. 


36h, Maximum Applications Exceeded (OS/2 Extended Edition 
only) 


Meaning: NetBIOS services requested in the Reset command are not 
available to this process because the number of processes it is currently 
serving is the maximum allowed by the NetBIOS load time parameters. 
This return code value only applies to the Reset command. 
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Required action: Eliminate a process that is using NetBIOS services 
or increase the value of the NetBIOS Application (APP) load time parame- 
ter and reboot. 


37h, No SAPs Available for NetBIOS (OS/2 Extended Edition only) 

Meaning: Another process has allocated an insufficient number of SAPs 
in its DIR. OPEN adapter request. All allocated adapter SAPs are already in 
use and none are left for NetBIOS. Thus, NetBIOS services are not avail- 
able to any process. Note that NetBIOS requires only one SAP to support 
all its processes. This return code value only applies to the Reset com- 
mand. 

Required action: Fix the first process. 


38h, Requested Resources Not Available (OS/2 Extended Edition 
only) 


Meaning: The requests for NetBIOS resources exceeds the number spec- 
ified at NetBIOS load time. The resources are names, commands, ses- 
sions, and the use of name number 01 h which can only be used by one 
process. NetBIOS is available for the application but with fewer re- 
sources. This return code value only applies to the Reset command. 

Required action: Adjust the necessary load time parameter. 


40h, System Error 

Meaning: Undocumented. 

Required Action: Undocumented. 


4lh, Hot Carrier from a Remote Adapter Detected 

Meaning: A remote adapter has a hot carrier. 

Required Action: Remove the offending adapter from the network 
and turn off your machine before trying to use the network again. 
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42h, Hot Carrier from This Adapter Detected 

Meaning-. A local adapter has a hot carrier. 

Required Action-. Remove the offending adapter from the network 
and replace it. 

43h, No Carrier Detected 

Meaning-. A local adapter cannot detect a carrier signal from the transla- 
tor unit. 

Required Action-. Determine why the adapter cannot detect a carrier 
signal and turn off your machine before trying to use the adapter again. 

4Eh, Status Bit 12, 14, or 15 on Longer than One Minute (Token- 
Ring) 


Meaning-. One or more of the ring status bits (12, 14, or 15) have been on 
longer than 60 seconds. This return code is not reported at all if ring sta- 
tus bits 8 through 11 are also on. 

Required Action-. Check the extended status last ring status code. The 
only NetBIOS Interface command that may be issued is Reset. 


4Fh, One or More of Status Bits 8-11 On 

Meaning-. One or more of ring status bits 8 through 11 are on. 

Required Action-. Check the extended status last ring status code. The 
only NetBIOS Interface command that may be issued is Reset. 


50h-F6h, Adapter Malfunction 

Meaning-. A local adapter is producing an invalid error code. 
Required Action-. Use another adapter. 


F7h, Error on Implicit DIR.INITIALIZE 

Meaning-. NetBIOS experienced an error when it attempted to initialize 
the LAN adapter. 
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Required Action: Check the extended status bring-up error code. 
The only NetBIOS Interface command that may be issued until this is 
done is Reset. 


F8h, Error on Implicit DIR. OPEN. ADAPTER 

Meaning: NetBIOS experienced an error when it attempted to open the 
LAN adapter. 

Required Action: Check the extended status bring-up error code. 
The only NetBIOS Interface command that may be issued until this is 
done is Reset. 

There is a possibility that a DIR.OPEN. ADAPTER could fail because 
of a temporary timing condition. Because of this the DIR.OPEN. 
ADAPTER is retried twice at 30 second intervals before reporting this re- 
turn code. 


F9h, IBM LAN Support Program Internal Error 

Meaning: The IBM Lan Support Program has experienced an internal er- 
ror. 

Required Action: Check the error code. The only NetBIOS Interface 
command that may be issued until this is done is Reset. 


FAh, Adapter Check 

Meaning: The adapter has experienced an internal error. 

Required Action: Check the adapter check reason code. The only 
NetBIOS Interface command that may be issued is Reset. 


FBh, NetBIOS Program Not Loaded in PC 

Meaning: The IBM LAN Support Program is not loaded and available. 
However, it has received a control block with a value greater than X'03' 
in the first byte indicating a NetBIOS command has been issued. 

Required Action: Load and start the IBM LAN Support Program and 
reissue the command or correct the control block. 
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FCh, DIR.OPEN.ADAPTER or DLC.OPEN.SAP Failed— Check 
Parameters 

Meaning-. As stated. 

Required Action-. Correct the parameters causing the error and exe- 
cute the DIR.OPEN.ADAPTER command again. Note, the DEC. OPEN. 
SAP command is executed on initial start and restart of the NetBIOS 
Interface. The parameters used are obtained from the DIR. OPEN. 
ADAPTER command (executed either explicitly or implicitly). 

There is a possibility that a DIR.OPEN.ADAPTER could fail because 
of a temporary timing condition, so before reporting this return code, 
the DIR.OPEN.ADAPTER is tried again twice at 30 second intervals. 


FDh, Unexpected Adapter Close 

Meaning-. The adapter was closed while the NetBIOS interface was exe- 
cuting a command. 

Required Action-. Issue a Reset command. 


F7h-FDh Error Notes 

Required Action-. The condition reported in the NcbRetCode is the last 
occurring error. 

Extended status information, excluding adapter counters, is available 
in the NcbReserve field. For Reset commands, it is the status prior to the 
Reset. 


Ring Status Information 

If any of ring status bits 8-11 are on, they cause error code 0x4F. 

If any of ring status bits 12, 14, or 15 are on for longer than 60 
seconds, they cause error code 0x4E. 0x4F errors have priority over 
0x4E errors. 

Ring status bits 6 and 7 do not cause errors. If ring status bit 7 
(counter overflow) is on, nothing is reported. Bit 6 (single station) is ig- 
nored. 

If a ring status appendage is not defined, local NetBIOS Interface 
counters are updated via the DIR.READ.LOG command. 
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Neb Command and Field Relationship 


Commands Listed by Command Code 


Command 

Command 

Code 

Retcode 

LSN 

Num 

Buffer® 

Length 

Call 

Name 

Name 

Rto 

Sto 

Post® 

Lana 

Num 

Call 

lOh, 90h 

O 

o 




I 

I 

D=0 

D=0 

C 

I 

Listen 

llh, 91h 

O 

o 




I/C 

(*) 

I 

D=0 

D=0 

C 

I 

Hang Up 

12h, 92h 

o 

I 








C 

I 

Send 

I4h, 94h 

o 

I 


I 

I 





C 

I 

Receive 

15h, 95h 

o 

I 


I 

I/O 





C 

I 

Receive- 

Any 

l6h, 96h 

o 

o 

I/C 

(FFH) 

I 

I/O 





C 

I 

Chain 

Send 

17h, 97h 

o 

I 


I 

I 

I 




C 

I 

Send 

Datagram 

2 Oh, AOh 

o 


I 

I 

I 

I 




C 

I 

Receive 

Datagram 

21h, Alh 

o 


I 

(FFH) 

I 

I/O 

O 




c 

I 

Send 

Broadcast 

Datagram 

22h, A2h 

o 


I 

I 

I 





c 

I 

Receive 

Broadcast 

Datagram 

23h, A3h 

o 


I 

I 

I/O 

O 




c 

I 

Add 

Name 

30h, BOh 

o 


O 




I 



c 

I 

Delete 

Name 

31h, Blh 

o 






I 



c 

I 

Legend: I Input, O Output, C Conditional 
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Commands Listed by Command Code (cont.) 


Command 

Command 

Code 

Retcode 

LSN 

Num 

Buffer® Length 

Call 

Name 

Name Rto 

Sto Post® 

Lana 

Num 

Reset 

32h 

O 

I 

I 





I 

Adapter 

Status 

33h, B3h 

O 



I I 

I 

(’) 


C 

I 

Session 

Status 

34h, B4h 

o 



I I/O 


I 

(*) 

c 

I 

Cancel 

35h 

o 



I 




I 

Add 

Group 

Name 

36h, B6h 

0 


O 



I 

c 

I 

Unlink 

70h 

o 







I 

Send 

No-Ack 

71h, Flh 

o 

I 


I I 



c 

I 

Chain 

Send 

No-Ack 

72h, F2h 

o 

I 


I I 

I 


c 

I 


Commands Listed by Categories 


Command 

Command 

Code 

Retcode 

LSN 

Num 

Buffer® Length 

Call 

Name 

Name Rto 

Sto Post® 

Lana 

Num 

Reset 

32h 

O 

I 

I 

General 




I 

Adapter 

Status 

33h, B3h 

O 



I I 

I 

(*) 


C 

I 

Cancel 

35h 

o 



I 




I 

Unlink 

70h 

o 







I 

Add 

Name 

30h, BOh 

o 


O 

Name 


I 

c 

I 

Delete 

Name 

31h, Blh 

o 





I 

c 

I 

Add 

Group 

Name 

36h, B6h 

o 


O 



I 

c 

I 

Call 

lOh, 90h 

o 

o 


Session 

I 

I D=0 

D=0 C 

I 
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Commands Listed by Categories (cont.) 

Command 

Command 

Code 

Retcode LSN 

Num 

Buffer® 

Length 

Call 

Name Name Rto 

Sto Post® 

Lana 

Num 

Listen 

llh, 91h 

O 

o 




I/C I D=0 

(*) 

D=0 C 

I 

Hang Up 

12h, 92h 

O 

I 




C 

I 

Send 

I4h, 94h 

o 

I 


I 

I 


C 

I 

Receive 

15h, 95h 

o 

I 


I 

I/O 


C 

I 

Receive- 

Any 

l6h, 96h 

o 

o 

I/C 

(FFH) 

I 

I/O 


C 

I 

Chain 

Send 

17h, 97h 

o 

I 


I 

I 

I 

C 

I 

Session 

Session 

Status 

34h, B4h 

o 



I 

I/O 

I 

(*) 

C 

I 

Send 
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Send No-Ack and Giain Send No-Ack 


When NetBIOS first appeared with the IBM PC Network LANA card, Net- 
BIOS insured data integrity for session traffic by sending an acknowledg- 
ment (ACK) for all messages successfully received with a Receive or 
Receive-Any command. When the IBM Token-Ring Network appeared, 
the IEEE 802.2 LLC layer also provided data receipt acknowledgments at 
a lower level in the communication layer hierarchy. However, the Token- 
Ring Network NetBIOS implementation continued to observe the prac- 
tice of NetBIOS-to-NetBIOS ACKing as a legacy, though it was somewhat 
unnecessary in theory. 

The Send No-Ack and Chain Send No-Ack commands, new with the 
IBM LAN Support Program version 1.02, are variants of the Send and 
Chain Send commands, respectively. Their purpose is to addtess the 
presence of redundant ACKing in IBM’s NetBIOS implementations. 
Their use potentially provides modest performance improvements for 
session-oriented communication by eliminating both the theoretically 
unnecessary adapter NetBIOS session overhead and LAN traffic caused 
by IBM’s NetBIOS-to-NetBIOS ACKing. 

IBM recommends (but does not require) that these commands be 
used with the IBM PC LAN Program 1.3 and beyond. While the Send No- 
Ack and Chain Send No-Ack commands require the same input fields as 
the Send and Chain Send commands, their use has serious side effects 
that need to be completely understood by programmers. 

Some NetBIOS implementations do not have these commands and 
the new 07h return code value they introduce. Use of these commands 
may produce nonportable results with side effects such as 03 h (invalid 
command) return code values in NetBIOS implementations not recog- 
nizing their command codes. 
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A LAN may have different levels of NetBIOS in use. If a NetBIOS im- 
plementation is presented a local Send No-Ack or Chain Send No-Ack 
command and determines that the remote NetBIOS cannot respond to 
the request appropriately, the local NetBIOS treats the request as a Send 
or Chain Send command, respectively In other words, there is no advan- 
tage in using the No-Acks in this scenario. 

A No-Ack command is not guaranteed delivery of its data. When a 
No-Ack command fails, the session remains intact because the NcbSto pa- 
rameter specified in the Call or Listen command that created the session 
has no effect on No-Ack commands. Moreover, a No-Ack command can 
be canceled without aborting the session. 

In these senses, a No-Ack command is somewhat like a Send 
Datagram command. However, No-Ack commands differ from Send 
Datagram commands because the message size can be 64K-1 characters 
for a Send No-Ack command and 128K-2 characters for a Chain Send No- 
Ack command. In addition, No-Ack commands specify an NcbLsn value 
and Send Datagram commands specify an NcbNum value. 

A No-Ack command may return with a final return code value of 
zero, but may have actually failed. The failure may be due to the target 
application’s not having any Receive or Receive-Any command outstand- 
ing. Here, the command completely fails but may have already reported 
its “success.” Or, if a Receive or Receive-Any command is outstanding, its 
buffer may not be large enough to hold all the arriving data. In this in- 
stance, the buffer is filled with data, and the remainder is discarded by 
NetBIOS. 

No-Ack command failures are reflected in other session commands. 
No-Ack commands that failed but return a final return code with a zero 
value cause other local session commands associated with the same LSN 
value to fail with a 07h final return code value. These commands are the 
Send, Send No-Ack, Chain Send, Chain Send No-Ack, Receive, and Re- 
ceive-Any commands. 

Whichever command NetBIOS finds first gets the lucky number 07h 
as a final return code. Hence, failure determination logic is complicated 
by the fact that the failure detection point is generally not predictable. In 
this sense, NetBIOS’s indiscrimination is most democratic. 

A 07h return code value is ambiguous in many ways. The 07h re- 
turn code value alerts an application that one or more No-Ack commands 
on the session have failed. No indication is given whether the command 
was one or more Send No-Ack command(s) and/or one or more Chain 
Send No-Ack command(s) or even how many No-Ack commands may 
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have failed. One 07h return code represents all of them in unison. Finally, 
if only one failed, no indication is given regarding how much data was 
actually successfully received. 

Receive or Receive-Any commands that receive data transmitted by 
a No-Ack command are given no indication that the data was transmit- 
ted by the No-Ack variant. If a Receive or Receive-Any command’s buffer 
is not large enough, the command completes with a 06h (incomplete re- 
ceived message) return code value as it does if the data was sent by a Send 
or Chain Send command. However, the application cannot issue another 
Receive or Receive-Any to obtain the remainder of the data because it has 
already been discarded by the local NetBIOS. Yet the receiving applica- 
tion has no way of knowing this. 

Applications such as the PC Network’s RPL logic depend on the abil- 
ity to issue a subsequent Receive to pending data. Here, as in many ex- 
isting programs, the RPL logic issues a Receive to obtain a message 
header which indicates the remaining data size that should be received 
with a subsequent Receive command. 


Conclusion 

No-Ack commands generally have the curious characteristic of unpre- 
dictably reflecting their problems in other commands. Clearly, tech- 
niques that work with the Send and Chain Send commands cannot be 
used with their No-Ack counterparts. Oddly enough, when things go 
wrong while using No-Ack commands, the most straightforward ap- 
proach is to use traditional Send and Chain Send commands to effect 
damage control. In any event, it is the application’s responsibility to 
maintain data integrity in No-Ack error sessions. 

It would seem that since traditional NetBIOS programming practices 
are generally inappropriate with the No-Ack commands, their use may be 
restricted to new applications. Otherwise, they may require significant 
restructuring of existing programs, exciting debugging opportunities, or 
both. 
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OS/2 Extended Edition 
and LAN Manager 


IBM’s OS/2 Extended Edition and Microsoft Corporation’s OS/2 Lan 
Manager contain extensions and changes to the PC-DOS NetBIOS Pro- 
gramming Interface. In both instances, NetBIOS functions are available 
via OS/2 dynamic linking. Processes present requests to NetBIOS using 
FAR CALL rather than PC-DOS INT 5Ch or 2Ah interrupts. Instead of 
pointing ES.BX to an Neb and executing an INT 5Ch, OS/2 assembly lan- 
guage programs use the following sequence: 

push NcbSeLector ; segment 

push NebOffset ; offset 

call NetBIOS ; NetBIOS dynamic link 


IBM OS/2 Extended Edition 

Many PC-DOS NetBIOS device driver load time parameter keywords, in- 
cluding all “old parameters,” are deleted and those that remain may have 
different defaults. Table F-1 lists the allowable parameters, their defaults, 
and their allowed values. The new APPLICATIONS parameter, specifies the 
number of processes that may simultaneously use the NetBIOS interface. 


OS/2 Extended Edition Reset Command 

In OS/2 Extended Edition, each process operates independently. A pro- 
cess obtains NetBIOS resources by a Reset command, which must be the 
first NetBIOS command a process issues. Processes cannot share names. 
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Table F-1. OS/2 Extended Edition Parameters 


Keyword 

Default 

Valid Values 

ADARADDR.NOT.REVERSED (ANR) 

NO 

Y(.es)/N(o) 

APPLICATIONS (APP) 

2 

0- 16 

COMMANDS (C) 

32 

0-255 

DATAGRAM.MAX (DG) 

NO 

Y(es)/N(o) 

DLC.MAXIN* (MI) 

- 

0-9 

DLC.MAXOUT* (MO) 

- 

0-9 

DLC.RETRY.COUNT* (RC) 

- 

0-255 

DLC.Tl (Tl) 

5 

0 - 10 

DLC.T2 (T2) 

2 

0 - 11 

DLC.Tl (TI) 

3 

0 - 10 

NAMES (N) 

17 

2 - 254 

RING.ACCESS (RA) 

0 

0 - 7 

REMOTE.DATAGRAM.CONTROL (RDC) 

NO 

Y(es)/N(o) 

REMOTE.NAME. DIRECTORY (RND) 

0 

0-255 

SESSIONS (S) 

32 

0 - 254 

STATIONS (ST) 

32 

0-254 

TRANSMIT.COUNT (TC) 

6 

0 - 10 

TRANSMIT.TIMEOUT (TT) 

1 

0-20 


* The adapter and interface code determines the default values for these parameters 


including the permanent name, and the right to use the permanent name 
is obtained using the Reset command. The OS/2 NetBIOS Reset com- 
mand is significantly different from the PC-DOS Reset command and is 
the only command which has redefined command field meanings. 


Storage Segment Seams 

In OS/2 NetBIOS requests, storage segment adjustments cannot be 
made. If an offset plus the data length of a buffer exceeds 64K in a Re- 
ceive, Receive-Any, Send, Send No-Ack, Chain Send, or Chain Send No- 
Ack command, the command completes with a return code value of 01 h 
(invalid buffer length). Because OS/2 Extended Edition locks storage 
communication buffers, buffers should be maintained in as few data seg- 
ments as possible. 
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Wait and No-Wait Options 

Commands specifying the wait option are initiated and the requesting 
process threads are immediately blocked. When the command com- 
pletes, execution returns to the requesting process’s code. The effect is 
similar to PC-DOS NetBIOS commands that specify a wait option. 

OS/2 Extended Edition processes no-wait commands by generating 
child threads that are immediately blocked. Execution then returns to 
the requesting process’s thread. When the command completes, Net- 
BIOS invokes a post routine if specified in the Neb. Post routines return 
by executing a PAR RETURN instruction rather than an IRET instruction 
and do not have to save or restore registers. 

Because commands specifying the no-wait option require more OS/2 
Extended Edition resources than commands specifying the wait option, 
commands specifying the wait option may succeed when commands 
specifying no- wait fail with a 35h return code value (required operating 
system resources exhausted). 


New Return Codes 

OS/2 Extended Edition adds several NetBIOS return codes. These are 
fully explained in the return codes discussion in Appendix C. 

30h: Name defined by another process 

34h; NetBIOS environment not defined. Reset must be issued 

35h: Required operating system resources exhausted 

36h: Maximum applications exceeded 

37h: No SAPs available for NetBIOS 

38h: Requested resource(s) not available 


Allocating and Deallocating NetBIOS Resources 

Processes issue the Reset command to allocate (reserve) and use or to 
deallocate (relinquish) and terminate using NetBIOS resources. 

Allocating Resources 

A process must issue a Reset command as its first NetBIOS command. 
Processes use the Reset command to request NetBIOS to allocate re- 
sources for their exclusive use. These resources are taken from the Net- 
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BIOS resource pool created at NetBIOS load time from the load time 
parameter values. Allocated resources cannot be used by any other pro- 
cess until they are released by the owning process. The requested re- 
sources are collectively called an environment and include a quantity of 
sessions, commands, names, and the use of name-number one. 

If the process subsequently issues a Reset command to redefine its 
environment, NetBIOS deallocates all resources currently reserved for 
the process and allocates the requested resources if they are available. 

Resetting and Deallocating Resources 

When a process issues a Reset command to deallocate its environment’s 
resources, NetBIOS returns all the resources allocated to the process to 
the NetBIOS resource pool for subsequent use by other processes. For 
the requesting process, existing sessions are terminated and all added 
names are deleted from the NetBIOS name table(s). Because all processes 
operate independently, no other currently executing process is affected. 

When an OS/2 Extended Edition process terminates, OS/2 EE implic- 
itly issues a NetBIOS Reset to deallocate resources the process owns. 


Microsoft Corporation’s OS/2 LAN Manager 

Microsoft Corporation’s OS/2 LAN Manager contains new functions that 
allow processes to access more than one installed NetBIOS device driver. 
These drivers can support multiple LAN adapters of the same or different 
types and each type has its own load time parameters. 

The new NetBIOS calls and their functions are 

• NetBiosEnum( ): Determines the number of and names of all in- 
stalled NetBIOS device drivers 

• NetBiosGetInfo( ): Returns installed NetBIOS device driver infor- 
mation for the specified driver 

• NetBiosOpen( ): Creates a device driver handle for sending Nebs 
to a specified NetBIOS device driver. The process specifies one of 
three operating modes in the call: 

Regular mode is simultaneously usable by multiple processes. 
It does not allow use of the permanent name or Reset, Receive 
Any-to-Any, or Receive Broadcast Datagram commands. 
Privileged mode is only usable by one process (though other 
processes can use or open the adapter in Regular mode simul- 
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taneously). It does not allow use of Reset or Receive Any-to- 
Any commands. 

Exclusive mode provides a process exclusive use of a NetBIOS 
device driver. This process can use any NetBIOS command. 

• NetBiosClose( ): Cancels the device driver handle, cancels any 
outstanding Nebs, and terminates access to a specified NetBIOS 
device driver, 

• NetBiosSubmit( ): Passes one or multiple Nebs to a specified Net- 
BIOS device driver. A chaining option specifies whether the re- 
quest is for one or multiple chained Nebs and is an efficient way to 
pass several requests to an individual NetBIOS device driver si- 
multaneously 

For single Neb requests, an error retry option specifies whether the 
LAN Manager should have the NetBIOS device driver retry a failing Neb 
request a specified number of times. For chained operations, a l6-bit off- 
set pointer precedes each Neb that points to the next Neb in the chain. 
All Nebs must be in the same segment and a value of OFFFFh specifies the 
end of the chain. 

A chain can contain any Neb sequence, but some are impractical. For 
example, a Send Datagram command may need an NebNum value that is 
returned by an Add Name command positioned earlier in the chain. The 
Send Datagram command fails because the Fan Manager does not auto- 
matically place the NebNum value in the Send Datagram Neb. 

For chained requests, an error retry option specifies whether the 
LAN Manager should have the NetBIOS device driver continue after an 
error (proceed-on-error) or terminate after an error (stop-on-error). 

Whether an Neb command specifying the no-wait option is an indi- 
vidual request or one within a chain, the LAN Manager implements no- 
wait requests with semaphore handles. Proceed-on-error chains typi- 
cally are used for no- wait option Neb commands. Stop-on-error chains 
are typically used with commands using the wait option. Nebs not proc- 
essed because of an earlier occurring error in the Neb chain are posted 
with a return code value of OBh (command cancelled). 
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Bibliography, 289 
BIOS 

actions on interrupt registers, 
158-59 

extended keystroke, 136 
LANA adapter, 160. See also 
Adapter(s) 

BIOS-ROM upgrade, 6-7 
Block device driver call interface, 
157-58 

Boot record, 163-64 
Booting up, 164 
Buffer 

Adapter Status, 92 
address for read/writes, 158 
application, 226 
data, 41, 162 
data hold, 51-52 
data-receive, 225 
depletion count counter, 233 
length, error code for a too-small, 
277 

length, error code for an invalid, 
277 

length status, 257 
offset, 42 

Receive, 33, 49, 54, 249-50 
SAP, 233 

segment address, 42 
Send Datagram, 137 
transmit, 49, 51 

Burned-in address (BIA), 21-22 
Bytewise Table Look-up CRC, 192-98 


C 

C post routine listing, 271-73 

C programming language 

file transfer applications, 139-53 
interrupt request program, 33-34 
Neb field structure example, 38 
program to test for presence of 
NetBIOS, 44-46 

CANCEL. C program listing, 88-92 


Carrier not detected, error code for 
a, 284 

Carrier Sense Multiple Access Carrier 
Detect (CSMA/CD) 
access method, 5, 13 
adapter, 77 

differences between Token-Ring 
environment and, 10 
Carry flag, 158, l6l, 163 
CB.C program listing, 119-37 
ApplyKeystroke( ) routine, 137 
EditArgs( ) routine, 134 
main( ) function, 133-34 
NetBIOS add name processing 
routines, 134 

Participate( ) routine, 134-35 
ProcessReceivedDatagram( ) 
routine, 136 

SendKeyboardMsg( ) routine, 137 
ServiceDatagramNcbs( ) routine, 

135- 36 

ServiceKeyboard( ) routine, 

136- 37 

Christensen, Ward, 170 
Client 

date and time application, 109-17 
defined, 155 

medialess workstations as, 155-56, 
159 

CLOSE. ON. RESET NetBIOS 
parameter, 51, 253 
Commands, NetBIOS. See NetBIOS 
commands 

COMMANDS NetBIOS parameter, 51, 
254 

Communications between 
applications 
datagrams for, 23-26 
sessions for, 23, 26-30 
CONFIG.SYS 

adapter opened during processing 
of, 54 

device driver specification line, 48 
diskette image’s, 164 
parameters, 226 

CRC-CCITT generation hardware, 

199 
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CRC-CCITT polynomial, 177-79 
and minimum look-up table sizes, 
199-205 

postconditioning for, 189 
CRC-16 polynomial, 177-78, 181-98 
generalized shifting of, 189-92 
hardware, 183-89 
CRC16.C program listing, 193-98 
CRC-32 polynomial, 207-17 

bytewise look-up table to generate 
values for a, 208-17 
postconditioning process, 207 
residual value, 207 
shifting, 207-8 

CRC32.C program listing, 209-17 
Create New File function (INT 21 h 
AH=5Bh), 59 

Create Unique File function (INT 21 h 
AH=5Ah), 59 

Cyclic Redundancy Checking (CRC), 
63, 167-217 

binary zero padding, 176 
bitwise reversal, 181-82, 184, 186 
calculation, 174-77, 201 
compatibility of implementations 
of, 198 

fundamentals, 169-79 
general mechanics, 181-98 
hardware, 183-89 
mathematics, 170-74 
message bit patterns, 175-76 
message receipt procedure, 177 
need for, 169-70 
polynomials, prevalent, 177-79 
postconditioning, 176, 188-89 
preconditioning, 175-76, 183-84 
process, 169-70 
residue, 201 

right-shifting in, 184, 186-88, 
189-92 

table look-up schemes, 192-98 
transmission procedure, 176 


D 

Data 


Data — cont 
encryption, 65 
layers, 156-59 
overlaid, 58 
sharing facilities, 159 
Data communication without a LAN, 
3 

Data Link Control (DLC), 8 
interface as communication 

programming interface by IBM, 
15-17 

software, 48-50 
Datagram 

conference, 119-37 
intermediate applications, 105-17 
origin name, 24 
sent to every network adapter 
with Send Broadcast Datagram 
command, 256 
Datagram support, 23-24 
broadcast, 24 
plain, 24-26 

programming application, 101-4 
DATAGRAM. MAX NetBIOS parameter, 
51 

Date application 
client, 109-17 
server, 105-9 

DATETIME. C program listing, 105-9 
DEBUG.COM program 

to examine the Network Adapter 
BIOS code, 9 

to show Network Adapter BIOS 
part number, 7 
Device driver 

block, 107-8, 159-60 
character, 107 

CONFIG.SYS specification line for 
a, 48 

invoking a, 108 

DHB. NUMBER NetBIOS parameter, 

51 

DHB. SIZE NetBIOS parameter, 

51-52, 233 

Direct interface as communication 
programming interface by IBM, 
15, 17 
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Directories, destroyed, 58 
DIR.INITIALIZE 
command, 235 

error code for an implicit, 284 
DIR.OPEN.ADAPTER 
command, 232, 235 
error code for a failed, 286 
error code for an implicit, 285 
DIR.READ.LOG 
command, 235 

interface counter updated with, 
286 

Diskette image, 163-65 
Display controller, 58 
DLC.MAXIN NetBIOS parameter, 48, 
52, 56 

DLC.MAXOUT NetBIOS parameter, 
48, 52, 56, 233 
DLC.OPEN.SAP 
command, 235 
failure, error code for a, 286 
DLC.RETRY.COUNT NetBIOS 
parameter, 52 

DLC.TI NetBIOS parameter, 53 
DLC.Tl NetBIOS parameter, 48, 52, 
56 

DLC.T2 NetBIOS parameter, 48, 52, 
56 

DXMINFO.DOC disk documentation 
file, 10, 22, 48, 50 

DXMTOMOD.SYS device driver, 8-9, 
48-49 

DXMTOMOD.SYS NAMES parameter, 
226 

DXMTOMOD.SYS TRANSMIT. 

COUNT parameter, 239, 240, 
241, 246, 257, 26l 
DXMTOMOD.SYS TRANSMIT 

TIMEOUT parameter, 239-41, 
246, 257, 261 


£ 

ENABLE NetBIOS parameter, 53 
Ethernet 
adapters, 15 


Ethernet — cont 

LANs, CRC-32 polynomial as CRC 
divisor in, 207 
network security, 65 
Exclusive-OR, 185, 193 
byte value, 192 
gates, 184 
table, 173 

Extended Graphics Adapter (EGA), 6 
EXTRA. SAPS NetBIOS parameter, 53 
EXTRA. STATIONS NetBIOS 
parameter, 53 


F 

File allocation tables (FATs), 
destroyed, 58 

File control blocks (FCBs), 58-59 

File transfer applications, C language, 
139-53 

File-handle functions for NetBIOS 
applications, 58 

Final return code, 223 

First-in, first-out (FIFO) order, 244, 
250 

Frames (transmitted packets), 49, 56 
information, 232-33 
maximum size of, 86-87 
unnumbered information, 232 


H 

Hardware 

CRC-CCITT, 199 
problem, error code for a, 280 
Header field, 170 


I 

IBM Academic Computing 

Information Systems (ACIS), 15 
IBM LAN Support Program, 4-6, 8-9, 
16, 17, 47-56, 221 
device driver, 22, 47 
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IBM LAN Support Program — cont 
internal error, error code for an, 
285 

not loaded, error code for, 285-86 
resetting an adapter controlled by 
the, 69-86 
role of, 47-48 
IBM NetBIOS Application 

Development Guide, 9, 10, 64 
IBM PC 

adding NetBIOS to an original, 

6-7 

IBM PC Network Adapter II 
operation in all but models 25 
and 30 of, 13 

IBM PC Network Baseband 
Adapter operation in, 14 
IBM Token-Ring Network PC 
Adapter operation in, 12 
IBM Token-Ring Network PC 
Adapter II operation in, 12 
IBM Token-Ring Network Trace 
and Performance Adapter 
operation in, 12 

test for the presence of NetBIOS in 
the, 35 

IBM PC LAN Adapter (LANA), 5 
number, 37, 43 

original PC Network card, 6-7 
IBM PC LAN Program (PCLP), 57-58, 
156 

coexistence restrictions, 58-59 
detecting the, 59-62 
executing the, 164 
IBM PC Local Area Network 

Program User's Guide, 57-59 
IBM PC Network 

baseband environment, 14 
broadband environment, 13 
CRC-32 polynomial as CRC divisor 
in, 207 
Ethernet, 15 

Token-Ring. See IBM Token-Ring 
network 

IBM PC Network Protocol Driver, 47 
IBM PC Network Technical Reference 
Manual, 9, 165 


IBM PC-AT 

IBM PC Network Adapter II 
operation in, 13 
IBM PC Network Baseband 
Adapter operation in, 14 
IBM Token-Ring Network PC 
Adapter operation in, 12 
IBM Token-Ring Network PC 
Adapter II operation in, 12 
IBM Token-Ring Network Trace 
and Performance Adapter 
operation in, 12 

test for the presence of NetBIOS in 
the, 35 

IBM PC-DOS to run NetBIOS, 5, 57 
IBM PC-XT 

IBM PC Network Adapter II 
operation in, 13 
IBM PC Network Baseband 
Adapter operation in, 14 
IBM Token-Ring Network PC 
Adapter operation in, 12 
IBM Token-Ring Network PC 
Adapter II operation in, 12 
IBM Token-Ring Network Trace 
and Performance Adapter 
operation in, 12 

test for the presence of NetBIOS in 
the, 35 

IBM Token-Ring network, 5,8 

adapter routing information for, 32 
CRC-32 polynomial as CRC divisor 
in, 207 

environment, 11-13 
IBM Token-Ring/PC Network 

Interconnect Program, 5, 48, 79 
IBMLANPG.C program listing, 59-62 
IBM's Local Area Networks: Power 
Networking and Systems 
Connectivity, 11 

IEEE 802.2 Logical Link Control 

(LLC) protocols, 4-5, 16-17, 48 
IEEE 802.3 Ethernet, 5 
Immediate return code, 223 
Inactivity timer (Ti), 53 
INT 13 

BIOS interface, 158-60 
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INT 13— cont 

reset command, I6I-63 
INT 21 

Create New File function (INT 21 h 
AH=5Bh), 59 

PC-DOS interface to resolve data 
requests, 156-57 
Integrity checking, 169 
International Standards Organization 
(ISO), 3-4 
Interrupt registers 

return code summary for, 261-62 
settings of, 226-29 
table of, 158, I63 

I/O redirection for character device 
drivers, 157. See also 
Redirectors 


K 

Keystroke, reading a, 136-37 


L 

LANA NetBIOS, 7-8 
LANA protocol ROM, 9 
LANAs Network Adapter BIOS, 5 
LANAS. INC, 9 

‘‘Layered hardware” design, 14 
Link stations, 49-50, 56 
device driver, 52 
obtaining additional, 53 
setting the maximum number of, 
55 

Local area network (LAN) 

data integrity and security, 63-65 
group names. See Network names 
monitors that record and display 
all data from Ethernet or Token- 
Ring, 65 

NetBIOS applications residing on 
different machines on a, 3 
programming interfaces, IBM, 
15-17 


Local area network (LAN) — cont 
real-time conferencing application, 
119-37 

Local node name, 21-22 
Local Session Number (LSN), 27, 30, 
241, 248, 253, 254, 260 
Logical Link Control (LLC) 
code retries, 52 
IEEE protocol, 4-5, 16-17, 48 
software, 48-50 
standard protocols, 47 
Look-up table sizes, minimum, 
199-205 

Low-order bit-first transmission rule, 
175 


M 

MAP/TOP environment 

implementations of NetBIOS, 6 
NetBIOS interface for, 5 
MASM 

interrupt request program, 34 
Neb field structure example, 39 
MAXDG.C program listing, 101-4 
Message Control block (Mcb). See 
Neb (NetBIOS Control Block) 
fields 

Message received incomplete, error 
code for, 277 

Microsoft LAN Manager, 156 
Microsoft Networks (MS-NET) 
redirector, 156 

Modulo two arithmetic, 172-74 
Modulo two division, 176, 184, 188 
Monitors that record and display all 
data from Ethernet or Token- 
Ring networks, 65 


N 

Name table, NetBIOS, 41, 53-54, 109, 
152 

adding a name to the, 240 
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deregistered name in the, error 
code for a, 279 

duplicate name in the, error code 
for a, 278 

full, error code for a, 279 
local, 236 

name deleted from the, error code 
for a, 280 

name missing from the, error code 
for a, 280 

name registration and the, 20-21 
network adapter name in the, 239 
program to add and delete names 
from the, 95-100 
Reset command to remove names 
from the, 31, 51, 58 

NAME.C program listing, 95-100 
AddNetbiosName routine, 99 
FillNetbiosNameTable routine, 
99-100 

NAMES NetBIOS parameter, 53-54, 
232 

Neb (NetBIOS Control Block) fields, 
32-33, 37-46, 221-28 
Buffer Address, 37, 41 
Buffer Length, 37, 41 
C language structure example, 38 
Call Name, 37, 41-42 
Command, 37, 39-40 
Command Complete Flag, 38, 43 
format, 222 
LANA Number, 38, 43 
Local Session Number, 37, 41 
MASM structure example, 39 
Name (Local), 37, 42 
Name number, 37, 41 
NcbBuffer@, 225, 232, 242, 243, 
254 

NcbCallName, 225-26, 232, 241, 
243, 247, 261 

NcbCmdCplt, 223, 228-30, 262 
NebCommand, 221-23 
NebLanaNum, 228, 232, 259, 261, 
281 

NcbLength, 225, 257 


Neb (NetBIOS Control Block) 
fields — cont 

NcbLsn, 224, 243, 246, 250, 254, 
260 

NcbName, 226, 241, 247, 257, 26l 
NebNameNum, 252, 260 
NebNum, 224, 240, 252, 253, 260 
NcbPost@, 227-30 
NebReserve, 228 
NebRetCode, 223-24, 229, 230, 
246, 261, 262, 286 
NebRto, 226-27, 241, 260 
NebSto, 227, 241, 247, 260 
Post Routine Address, 38, 43 
Receive Time Out, 37, 42 
Reserved Field, 38, 43 
Return Code, 37, 40 
Send Datagram, 104 
Send Time Out, 37, 42 
structure of, 37-39 
NETBEUI. COM (NetBIOS Extended 
User Interface) module, 8-10, 
47 

NetBIOS commands, 35, 231-62, 
287-89 

Adapter Reset, 20 
Adapter Status, 31-32, 50, 70, 77, 
89, 91-92, 101, 161, 225-26, 
231-38, 248, 257, 26l, 280 
Add Group Name, 224, 226, 239, 
281 

Add_Group_Name_Claim, 20 
Add Name, 152, 224, 226, 240, 

281 

Call, 26, 42, 54, 153, l6l, 225-27, 
236, 241-42, 244-45, 249, 255, 
280 

Cancel, 31, 91-92, 222, 225, 227, 
242, 247, 255, 278, 281 
canceled, error code for, 278, 281 
Chain Send, 28-29, 42, 221, 
225-27, 241-44, 246-47, 255, 
261 

Chain Send No-Ack, 30, 242-44, 
248 

completion message, 276 
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Delete Name, 20, 226, 236, 
244-45, 280 
Find, 32 

Find Name, 31-32, 54 
Hang Up, 30, 92, 153, l64, 165, 
243, 245-47, 249, 254-55, 259, 
261 

invalid, error code for, 277 
issuing, 32 

list by categories, 288-89 
list by command code, 287-88 
Listen, 26, 42, 152-53, 225-27, 
236, 244-45, 247-49, 255, 26l, 
279 

Name_Claim, 20 
pending, error code for too many, 
281 

Receive, 27-29, 33, 42, 153, 
162-63, 225-27, 241, 246, 
248-50 

Receive-Any 224, 225-27, 240, 
246, 249-50, 26l 
Receive-Any Datagram, 25 
Receive-Any-for-a-Specified-Name 
(Receive-Any), 27-29, 250 
Receive-Any-for-Any-Name 
(Receive- Any- Any), 27-29, 58, 

250, 260 

Receive Broadcast Datagram, 58, 
225, 251, 256 

Receive Datagram, 24-25, 109, 
116-17, 134-35, 224, 225, 

252- 53, 256, 260 

Reset, 31, 51, 55, 58, 76, 222, 224, 

253- 54, 260, 283, 284 
returning to the operating system 

with still-pending, 40 
Send, 28-30, 42, 153, 162, 225, 
227, 241-42, 246-47, 254-55, 
261, 280 

Send Broadcast Datagram, 24, 225, 

251, 255-56 

Send Datagram, 24, 54, 104, 137, 
225, 256 

Send No-Ack, 30, 242, 248, 

254- 55 
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Session Status, 225, 226, 257-58, 
261 

Status Query, 54 
timed-out error code, 275 
Trace, 32 

uncompleted, 39-40, 43, 91-92 
Unlink, 31, 92, l65, 222, 259, 260 
NetBIOS interrupt request 
sample C, 32-33 
sample MASM, 33-34 
NetBIOS ROM, 7 
NETBIOS.COM 

to replace PC Network LANA 
NetBIOS, 8 

testing for presence of NetBIOS 
complicated by, 46 
NetBIOS2.h program listing, 109, 
265-70 

Network Adapter BIOS, 7 
listing, 9 
part number, 7 

Network Adapter/A (Token-Ring), 12, 
49 

Network Adapter II, 47-48 
Broadband, 13 
Token-Ring, 12, 49 
Network Adapter III A, 13, 47-48 
Network Basic Input/Output System 
(NetBIOS) 

application services, 19-35 
command code, 39 
command completion, 228-30 
as communication programming 
interface by IBM, 15 
as de facto industry standard, 5 
defined, 3 

device driver, 51-55 
error codes, 76-77, 275-86 
error information, 43 
history, 5 

Interface, 8, 10, 32, 279 
introduction to, 1-65 
network security features not built 
into, 64 

no-wait option, 39, 43, 89, 153, 
221-23, 228-29 
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Network Basic Input/Output System 
(NetBIOS) — com 

operating system environments 
for, 5, 57 

parameter summary, 48-56 
post routine, 227-28 
reference material, descriptions of, 
9-10 

relationships to other IBM 
products, 57-62 
support programming, 67-165 
TCP/IP implementations of, 6 
technical reference, 219-60 
testing for the presence of, 34-35, 
44-46 

Network name(s) 

failure to register, 20 
group, 20 

identical multiple, error code for, 
280 

legal characters in, 19 
number, 20-21, 279 
permanent node, 21-22 
symbolic, 22-23 
table. See Name table, NetBIOS 
unique, 20 

Network PC Adapter, 12 
Network PC Adapter II, 12 
Network Trace and Performance 
Adapter/A, 12 

Network Trace and Performance 
Adapter II, 12 

Nibblewise table look-up, 201-5, 209 


0 

Open Systems Interconnection (OSI) 
Reference Model, 3-4 
OPEN. ON. LOAD NetBIOS parameter, 
54 

OS/2 

LAN Requestor function, 156 
to run NetBIOS, 5 
OS/2 Extended Edition, l6, 156 


P 

Packet acknowledgment protocol, 26 
Packets. See Frames (transmitted 
packets) 

Parameters, NetBIOS, 48-56 
processing, 79-80 
Parity checking, 63, 169 
PC BIOS Extended BIOS Option, 6 
PC Network Adapter, 5, 12, 49 
information format for status of, 
237-38 

PC Network LANA RPL protocols, 12, 
31 

PC Network Protocol Driver 
Program, 10 
PC-DOS redirector, 57 
PC-DOS Technical Reference 
Manual, 59, 158, l60 
PC-XT Fixed Disk Adapter, 6 
Peer-layer communication, 4 
Peer-to-peer communications, APPC 
interface for, 16 

Permanent node name, 21-22, 31, 

50, 105 

abuse of, 64-65 
fetching the, l6l 
Physical address, 21-22 
Polynomial division 
algebraic, 171-73 
modulo two arithmetic and, 
172-74, 184, 188 

POST processing queue, 223-24, 

229 

Power-On-Self-Tests (POST), 7 
PRESENCE. C program to test for 
presence of NetBIOS, 44-46 
Program listings 
CANCEL.C, 88-92 
CB.C, 119-37 
CRC16.C, 193-98 
CRC32.C, 209-17 
DATETIME. C, 105-9 
IBMLANPG.C, 59-62 
MAXDG.C, 101-4 
NAME.C, 95-100 
PRESENCE. C, 44-46 
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RECEIVE. C, 146-52 
RESET.C, 69-75 
SEND.C, 139-46 
SET_D__T.C, 109-17 
STATUS. C, 78-86 
UNLINK.C, 92-93 
Protocol ROM, 5 
PS/2 

IBM PC Network Adapter II/A 
operation in all but models 25 
and 30 of, 13 

IBM PC Network Baseband 
Adapter/A operation in all but 
models 25 and 30 of, 14 
IBM Token-Ring Network Adapter/ 
A operation in all but models 25 
and 30 of, 12 

IBM Token-Ring Network Trace 
and Performance Adapter/A 
operation in all but models 25 
and 30 of, 12 
PS/2 model 25 

IBM PC Network Adapter II 
operation in, 13 
IBM PC Network Baseband 
Adapter operation in, 14 
IBM Token-Ring Network PC 
Adapter operation in, 12 
IBM Token-Ring Network PC 
Adapter II operation in, 12 
IBM Token-Ring Network Trace 
and Performance Adapter 
operation in, 12 
PS/2 model 30 

IBM PC Network Adapter II 
operation in, 13 
IBM PC Network Baseband 
Adapter operation in, 14 
IBM Token-Ring Network PC 
Adapter operation in, 12 
IBM Token-Ring Network PC 
Adapter II operation in, 12 
IBM Token-Ring Network Trace 
and Performance Adapter 
operation in, 12 


Q 

Queries 

TRANSMIT. COUNT parameter to 
specify number of times to 
transmit, 55 

TRANSMIT. TIMEOUT parameter 
to specify number of intervals 
between transmission of, 56 


R 

Read requests, 162 
RECEIVE. BUFFER. SIZE NetBIOS 
parameter, 54 

RECEIVE. C program listing, 139, 
146-53 

Receiver acknowledgment timer (T2), 
52 

Redirection logic, l6l-65 
Redirector(s) 
attributes, 155 
examples of, 156 
implementation, 159 
REDIR.EXE redirector module, 57, 
159 

Remote Program Load (RPL) 
attributes, 155 
implementation, 160-65 
to load operating systems for 
medialess workstations, 156 
logic, entering the, l6l 
server, unlinking from, 164-65, 
259 

surrogate diskette boot process, 5 
Remote Virtual Disk (RVD), 159 
REMOTE.DATAGRAM. CONTROL 
NetBIOS parameter, 54 
REMOTE.NAME. DIRECTORY 
NetBIOS parameter, 54 
RESET.C program to reset an adapter, 
69-75 

AnalyzeResetError( ) routine of 
the, 76-77 

EditParms( ) routine of the, 75-76 
ResetAdapter( ) routine of the, 76, 
77 
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RESET. VALUES NetBIOS parameter, 
55, 253-54 

Residue after a CRC message is 
received, 177 
Response timer (Tl), 52 
Return code summary, 261-62 
Ring status bits 8 through 11 error 
codes, 284, 286 

Ring status bits 12, 14, and 15 error 
codes, 284, 286 

RING. ACCESS NetBIOS parameter, 

55 

RING. STATUS. APPENDAGE field 
pointer, 232-33 
ROM BASIC, 161 

interrupt vector (INT 18), I6O-6I 
RPL. PC Network LANA RPL 

protocols and Remote Program 
Load (RPL) 


S 

SDLC/HDLC polynomial, 178 
SEND.C program listing, 139-46 
Server 

application, date and time, 105-9 
defined, 155 

Service Access Point (SAP), 48-50 
buffer, 233 

opening the, 235, 283 
Session Management Protocol (SMP), 
4, 47 

Sessions for communications 

abnormally ended, error code for, 
280 

advantages and disadvantages of, 
26 

applications should not use all 
available, 58 

closed, error code for, 278 
creating, 26-27 

deregistered name error code for, 
278 

graceful ending for, 30 
invalid number for, 278 
local, 26, 275, 278 


Sessions for communications — cont 
number field, local, 41 
partners in, 26 
pending, 236 
remote, 26 

setting the maximum number of, 
55 

status determined with Session 
Status command, 257-58 
table, 164, 279 

SESSIONS NetBIOS parameter, 55, 
253 

SET_D_T.C, 109-17 
Shared-RAM, 12 
Special values, 26O-6I 
Start of Header (SOH) character, 170 
Start of Text (STX) character, 170 
STATIONS NetBIOS parameter, 
48-49, 55 

STATUS. C program listing, 78-86 
DisplayNetbiosLevel( ) routine, 80 
DlcStatus( ) routine, 80 
EditArgs( ), 78-80 
main( ) routine, 78 
Support programming, NetBIOS, 
67-165 

datagram, 101-4 
general, 69-93 
name, 95-100 
System error, 279 
System reset (Ctrl-Alt-Del), 20, 58 
Systems Network Architecture (SNA), 
APPC interface for, I6 
Sytek, Inc., 5 


T 

TCP/IP 

implementations of NetBIOS, 6 
NetBIOS interface for, 5 
Time application 
client, 109-17 
server, 105-9 
Timer tick rate, 59 
Token-Ring Adapters 
five types of IBM, 12 
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Token-Ring Adapters — cont 

information format for adapter 
status, 232-37 

Token-Ring environment, 11-13 
data security, 65 

Token-Ring Network PC Adapter 
Technical Reference Manual, 
9-10, 64, 77 

Token-Ring Technical Reference 
Manual, 8, 52-53 

TOKREUI.COM (Token-Ring 
Extended User Interface) 
module, 8, 47 

Topology 

branching- tree, 13 
ring, 11 

Transceiver Interface Register, 14 

TRANSMITCOUNT NetBIOS 
parameter, 55 

TRANSMITTIMEOUT NetBIOS 
parameter, 56 


U 

Unit identification number, 21-22 


Universally administered address, 
21-22 

UNIX to run NetBIOS, 5, 57 
UNLINK. C program listing, 92-93 


V 

Virtual circuits, 26 
Virtual drive, 159 


W 

Workstations, medialess 
attributes, 155 

RPL used to load operating system 
for, 156 

Write requests, 162 

Writing MS-DOS Device Drivers, 158 


X 

XMODEM check sum, 170 
XMODEM protocol, 170 





The Waite Group’s 
Advanced C Primer + + 

Stephen Praia, The Waite Group 

Programmers, students, managers, 
and hackers alike, will learn to 
master the C programming lan- 
guage. Anyone who knows the bas- 
ics of C will learn practical C tips 
never before published. This in- 
depth coverage gives you rare and 
complete examination of video ac- 
cess ports, segmented memory, and 
registers. 

Advanced C Primer + + takes the 
reader further than most C books 
on the market, showing how to 
manipulate the hardware of the 
IBM PC family of computers direct- 
ly from C. Readers learn how to 
access routines in the Read Only 
Memory (ROM) of an IBM PC, how 
to use system calls in PC DOS 
from C and i/o ports, how to con- 
trol the video screen, and to inte- 
grate assembly routines into C 
programs. 

Topics covered include: 

■ Advanced C Programming 

■ Register and Bit Level System 
Control 

■ Hardware Operation for Begin- 
ners and Experienced Users 

■ Advanced Use of Pointers, 
Functions, Storage Classes, 
Arrays and Structures 

■ C Library Access 

■ Use of Assembly Language 
Modules 

■ Binary and Text File Input 
and Output 

Includes chapter questions and 
answers. 

512 Pages, 7^2 x 9%, Softbound 
ISBN: 0-672-22486-0 

No. 22486, $24.95 


The Waite Group’s 
Microsoft® C Bible 

Nabajyoti Barkakati, The Waite Group 

Microsoft C Bible provides a thorough 
description of the 370 functions of the 
Microsoft C library, complete with prac- 
tical, real-world MS-DOS-based examples 
for each function. Library routines are 
broken down into functional categories 
with an intermediate-level tutorial fol- 
Jowed by the functions and examples. 

Included are two “quick-start” tutorials, 
complete ANSI prototypes for each func- 
tion, extensive program examples, and 
handy jump tables to help enhance 
learning. 

Topics covered include: 

■ Overview of the C Language 

■ Microsoft C 5.0 Compiler Features 
and Options 

■ Process Control 

■ Variable Length Argument Lists 

■ Memory Allocation and Management 

■ Buffer Manipulation 

■ Data Conversion Routines 

■ Math Routines 

■ Character Classification and 
Conversion 

■ String Comparison and Manipulation 

■ Searching and Sorting 

■ Time Routines 

■ File and Directory Manipulation 

■ Input and Output Routines 

■ System Calls 

■ Graphics Modes, Coordinates, 
and Attributes 

■ Drawing and Animation 

■ Combining Graphics and Text 

824 Pages, Vh x 9%, Softbound 
ISBN: 0-672-22620-0 

No. 22620. $24.95 


The Waite Group’s 
Microsoft® C Programming 
for the IBM® 

Robert Lafore, The Waite Group 

Programmers using the Microsoft C 
compiler can learn to write useful 
and marketable programs with this 
entry level book on Microsoft C 
programming. 

This title is a tutorial geared specif- 
ically to the IBM PC family of 
computers. Unlike other introducto- 
ry C titles, it is written for the 
Microsoft C compiler. It provides 
special coverage of IBM features 
such as sound, color graphics in- 
cluding CGA and EGA, keyboard, 
telecommunications, and character 
graphics. 

Topics covered include: 

■ Getting Started 

■ Building Blocks 

■ Loops 

■ Decisions 

■ Functions 

■ Arrays and Strings 

■ Pointers 

■ Keyboard and Cursor 

■ Structures, Unions, and ROM 
BIOS 

■ Memory and the Monochrome 
Display 

■ CGA and EGA Color Graphics 

■ Files Preprocessor 

■ Serial Ports and Telecom- 
munications 

■ Larger Programs 

■ Advanced Variables 

■ Appendices: Supplementary Pro- 
grams, Hexadecimal Numbering, 
IBM Character Codes, and a 
Bibliography 

640 Pages, 7 ’72 x 9%, Softbound 
ISBN: 0-672-22515-8 

No. 22515, $24.95 


The Waite Group’s 
Turbo C® Programming for 
the IBM® 

Robert Lafore, The Waite Group 

This entry-level text teaches readers 
the C language while also helping 
them write useful and marketable 
programs for the IBM PC, XT, AT, 
and PC/2. 

This tutorial is based on Borland’s 
new Turbo C compiler with its 
powerful integrated environment 
that makes it easy to edit, compile, 
and run C programs. The author’s 
proven hands-on intensive approach 
includes example programs, exer- 
cises, and questions and answers 
and covers CGA and EGA graphic 
modes. 

Topics covered include: 

■ C Building Blocks 

■ Loops 

■ Decisions 

■ Functions 

■ Arrays and Strings 

■ Pointers 

■ Keyboard and Cursor 

■ Structures, Unions, and ROM 
BIOS 

■ Memory and the Character 
Display 

■ CGA and EGA Color Graphics 

■ Files 

■ Larger Programs 

■ Advanced Variables 

■ Appendices: References, Hexa- 
decimal Numbering, Bibliogra- 
phy, “ASCII Chart, and Answers 
to Questions and Exercises 

608 Pages, 7V2 x 9%, Softbound 
ISBN: 0-672-22614-6 

No. 22614, $22.95 


Visit your local book retailer, use the order form provided, or call 800-428-SAMS. 



Revised E^tion 

Stephen G. Kochan 

This timely revision provides complete 
coverage of the C language, including 
all language features and over 90 pro- 
gram examples. The comprehensive 
tutorial approach teaches the beginner 
how to write, compile, and execute pro- 
grams and teaches the experienced pro- 
grammer how to write applications 
using features unique to C. It is written 
in a clear instructive style and is ideally 
suited for classroom use or as a self- 
study guide. 

Topics covered include: 

■ Introduction and Fundamentals 

■ Writing a Program in C 

■ Variables, Constants, Data Types, 
and Arithmetic Expressions 

■ Program Looping 

■ Making Decisions 

■ Arrays 

■ Functions 

■ Structures 

■ Character Strings 

■ Pointers 

■ Operations on Bits 

■ The Preprocessor 

■ Working with Larger Programs 

■ Input and Output 

■ Miscellaneous and Advanced Features 

■ Appendices: Language Summary, 

ANSI Standard C, Common Program- 
ming Mistakes, the UNIX C Library, 
Compiling Programs under UNIX, 
the Program LINT, the ASCII 
Character Set 

476 Pages, Vk x 9y4, Softbound 
ISBN: 0-672-48420-X 

No. 48420, $24.95 


Programming in ANSI C 

Stephen G. Kochan 

This comprehensive tutorial assumes no 
previous exposure to the C language. It 
teaches programmers, systems analysts, 
and students, how to write, compile, 
and execute C programs and how to 
write applications. 

The book provides a complete introduc- 
tion to ANSI standard C and contains 
over 90 program examples with step-by- 
step explanations of each procedure. 
Written in a clear, instructive style with 
end-of-chapter exercises, it is ideal for 
self-study or classroom use. 

Topics covered include: 

■ Introduction and Fundamentals 

■ Writing a Program in ANSI C 

■ Variables, Data Types, and 
Arithmetic Expressions 

■ Program Looping 

■ Making Decisions 

■ Arrays, Functions, Structures 

■ Character Strings, Pointers 

■ Operations on Bits 

■ The Preprocessor 

■ More on Data Types 

■ Working with Larger Programs 

■ Input and Output 

■ Miscellaneous Features and Topics 

■ Appendices: ANSI C Language Sum- 
mary, The UNIX C Library, Compil- 
ing Programs Under UNIX, The Pro- 
gram LINT, The ASCII Character Set 

450 Pages, 7 ‘A x 9%, Softbound 
ISBN: 0-672-48408-0 

No. 48408, $24.95 


Advanced C: Tips and 
Techniques 

Paul L Anderson and Gail C. Anderson 

This in-depth book on C looks at porta- 
bility, execution efficiency, and program- 
ming application techniques. Examples 
and techniques are portable across to- 
day’s popular operating systems, making 
it appropriate for professional program- 
mers, applications developers, systems 
level engineers, and programming 
students. 

Entire chapters are devoted to special 
areas of C such as debugging tech- 
niques, C’s run-time environment, and 
arrays and pointers. Techniques for 
allocating storage for multidimensional 
arrays at run-time, working with com- 
plex C expression, and speeding up pro- 
grams with multidimensional arrays are 
presented clearly with realistic examples 
that demonstrate the techniques. 

Topics covered include: 

■ C Refresher 

■ The Run-Time Environment 

■ Bits of C 

■ There’s No Such Thing as an Array 

■ C Debugging Techniques 

■ A Memory Object Allocator 

■ Appendices: Portable C Under UNIX 
System V, Microsoft C Under XENIX, 
Microsoft C Under DOS, Turbo C 
Under DOS 

325 Pages, Vh x 9%, Softbound 
ISBN: 0-672-48417-X 

No. 48417, $24.95 


Topics in C Programming 

Stephen G. Kochan and Patrick H. Wood 

Here is the most advanced and com- 
prehensive coverage of the maturing C 
market. This sequel to Programming in 
C describes in detail some of the most 
difficult concepts in the C language- 
structures and pointers. It also explores 
the standard C library and standard I/O 
library, dynamic memory allocation, 
linked lists, tree structures, and dispatch 
tables. 

Experienced C programmers can ex- 
amine the UNIX System Interface 
through discussions on controlling pro- 
cesses, pipes, and terminal I/O. Topics 
in C Programming also explains how 
to write terminal-independent programs, 
how to debug C programs and analyze 
their performance, and how to use 
“make” for automatic generation of a 
programming system. 

Topics covered include: 

■ Structures and Pointers 

■ The Standard C Library 

■ The Standard I/O Library 

■ UNIX System Interface 

■ Writing Terminal Independent Pro- 
grams with “curses” Library 

■ Debug and Performance Analysis of 
C Programs 

■ Generating Program Systems 
with “make” 

528 Pages, V/i x 9%, Softbound 
ISBN: 0-672-46290-7 

No. 46290, $24.95 


Visit your local book retailer, use the order form provided, or call 800-428-SAMS. 



C Programmer’s Guide to 
Serial Communications 

Joe Campbell 

This book offers a comprehensive 
examination and unprecedented dis- 
section of asynchronous serial com- 
munications. Written for C 
programmers and technically ad- 
vanced users, it contains both a 
theoretical discussion of com- 
munications concepts and a practi- 
cal approach to program design for 
the IBM® PC and Kaypro en- 
vironments. 

Topics covered include: 

■ The ASCII Character Set 

■ Fundamentals of Asynchro- 
nous Technology 

■ Errors and Error Detection 

■ Information Transfer 

■ Modems and Modem Control 

■ The UART— A Conceptual 
Model 

■ Real-World Hardware: 

Two UARTs 

■ The Hayes Smartmodem 

■ Designing a Basic Serial I/O 
Library 

■ Portability Considerations 

■ Timing Functions 

■ Functions for Baud Rate and 
Data Format 

■ RS-232 Control 

■ Formatted Input and Output 

■ Smartmodem Programming 

■ XMODEM File Transfers 

■ CRC Calculations 

■ Interrupts 

672 Pages, Vk x 9%, Softbound 
ISBN: 0-672-22584-0 

No. 22584, $26.95 


Portability and the C Language 

Rex Jaeschke 

Portability, the feature that distin- 
guishes C from other programming 
languages, is thoroughly defined 
and explained in this definitive 
reference work. The book primarily 
addresses the technical issues of 
designing and writing C programs 
that are to be compiled across a 
diverse number of hardware and 
operating system environments. 

Organized around the ANSI C Stan- 
dard, it explains the C preprocessor 
and the run-time library and tackles 
portability from a C language per- 
spective, discussing implementation- 
specific issues as they arise. 

Topics covered include: 

■ Introduction and Overview 

■ The Environment 

■ Conversions, Expressions, 
Declarations, and Statements 

■ The Preprocessor 

■ Diagnostics, Character Handling, 
Errors 

■ Numerical Limits and Locali- 
zation 

■ Mathematics, Non-Local Jumps, 
Signal Handling 

■ Variable Arguments and 
Common Definitions 

■ Input/Output, General Utilities, 
String Handling 

■ Date and Time 

■ Appendix: Keywords and 
Reserved Identifiers 

400 Pages, 7V2 x 9%, Softbound 
ISBN: 0-672-48428-5 

No. 48428, $24.95 


C Programmer’s Guide to 
Microsoft® Windows 2.0 

Carl Townsend 

This intermediate-level program- 
ming guide shows the C program- 
mer how to create applications 
under the Windows environment. 
Emphasizing the Microsoft C com- 
piler, a sample application is 
presented along with the rationale 
behind its development. 

Written as a tutorial, the book 
shows the experienced programmer 
how to exploit the extended fea- 
tures of Windows, providing an al- 
phabetical list of functions and an 
easy-to-use guide to those extended 
features including printing, 
accelerators, and the GDI interface. 

Topics covered include: 

■ Windows Overview 

■ The User Interface 

■ The Role of Messages 

■ The WinMain Program 

■ Managing Text with Windows 

■ Creating Menus and Using 
Dialog Boxes 

■ The Graphic Interface 

■ Windows, I/O, and Memory 
Management 

■ Creating and Managing Libraries 

■ Data Transfer 

■ Debugging Strategies 

M Appendices: Installation, 

Message Boxes, Keyboard Inter- 
face, Function Summary, Using 
Windows with Pascal or As- 
sembly Languages, Glossary 

440 Pages, 7V2 x 9%, Softbound 
ISBN: 0-672-22621-9 

No. 22621, $24.95 


QuickC™ Programming 
for the IBM® 

Carl Townsend 

This book is an entry-level tutorial 
for the beginning C programmer 
who desires to develop programs 
using the Microsoft® QuickC com- 
piler. It will also acquaint the busi- 
ness professional or serious user 
with the basic aspects of program- 
ming in C. 

The book includes hands-on inter- 
action between the high-speed, low- 
cost compiler and the IBM® PC. 

Topics covered include: 

■ Getting Started 

■ Representing Data 

■ Basic Input and Output 

■ Arithmetic Operations 

■ Program Control: IF, CASE, 
and Iteration Structures 

■ Using Functions and Macros 

■ Managing the Storage of 
Variables 

■ Arrays and Pointers 

■ Using Character Strings, Data 
Structures, Files and Other 
I/O, and Graphics 

■ Introduction to Structured 
Programming 

■ Developing ftograms with 
QuickC 

■ Managing Databases with 
QuickC 

■ High-level Design: Menus 

■ Adding Database Records 

■ Editing and Deleting Records 

■ Reporting and Processing 
Programs 

400 Pages, Vk x 9%, Softbound 
ISBN: 0-672-22622-7 

No. 22622, $22.95 


I 


Visit your local book retailer, use the order form provided, or call 800-428-SAMS. 



C with Excellence: 
Programming Proverbs 

Henry Ledgard with John Tauer 

C programmers will learn how to in- 
crease their programming skills and to 
write carefully constructed and readable 
programs with this handbook on C 
programming. Its clear and concise style 
provides both the novice and the experts 
programmer with guidelines or 
“proverbs” for writing high-quality, 
error-free software. 

The reader familiar with the fundamen- 
tals of C, BASIC, or Pascal will be able 
to apply these principles to develop sys- 
tems and applications software as well 
as write C programs that can be easily 
ported from one microcomputer to 
another. 

After introducing the 24 “proverbs” and 
their applications, this handbook focuses 
on the entire development process from 
conceptualizing to coding, documenting, 
testing, debugging, and maintaining and 
modifying programs. 

Topics covered include; 

■ Programming Proverbs 

■ Structure Is Logic 

■ Coding the Program 

■ Global Variables, Selecting Names, 
Recursion, and Efficiency 

■ Top-down Programming 

■ Appendices: Summary of Program 
Standards and a Program for 
Kriegspiel Checkers 

272 Pages, Vh x 9%, Softbqund 
ISBN: 0-672-46294-X 

No. 46294, $18.95 


C+ + Programming Guide 
for the IBM® 

John Berry and Mitchell Waite, 

The Waite Group 

C+ + Programming Guide for the 
IBM is a complete guide and tutori- 
al to the C++ language specifical- 
ly adapted to the IBM PC family. 

Aimed at developers and students, 
it teaches the use of object-oriented 
programming skills and introduces 
the major features of the language 
with explanations followed by prac- 
tical examples. It builds three 
professional libraries— cEntry, 
cGraphics, and cWindows— which 
enable programmers and developers 
to find shortcuts to the often cum- 
bersome programming process. 

Topics covered include: 

■ How the C++ Translator 
Works 

■ New C+ + Syntax 

■ The C + + Stream h. Library 

■ The Inline Functions 

■ What the New C++ Pointers 
Offer 

■ Memory Allocation Functions 

■ Void Type Pointer to Generic 
Object 

,■ New C+ + Structured Data 
. Type Versus the Old 

■ Private and Public Structures 

■ Hiding the Implementation 

■ Access by Non-member 
Functions 

■ Constructors and Destructors 

■ Overloading Functions and 
Operators 

400 Pages, Vh x 9%, Softbound 
ISBN: 0-672-22619-7 

No. 22619, $24.95 


The Waite Group’s 
Turbo C Bible 

Naba Barkakati 

Clear and well-written tutorials 
point out the different purposes 
and appropriate uses of each Turbo 
C function to make programming 
more organized, complete, and 
powerful. The library routines are 
organized into functional categories 
with explanations that include the 
purpose, syntax, example call, in- 
cludes, common uses, returns, com- 
ments, cautions and pitfalls, and 
cross-reference for that function. 
Unique compatibility check boxes 
show portability with Microsoft C 
versions 3.0, 4.0, and 5.0; Microsoft 
QuickC, and the UNIX System V 
compilers. 

Topics covered include: 

■ Overview of the C Language 

■ Turbo C 1.0 Compiler Features 
■ and Options 

■ Process Control 

■ Variable-Length Argument Lists 

■ Memory Allocation and Manage- 
ment 

■ Buffer Manipulation 

■ Data Conversion Routines 

■ Math Routines 

■ Character Classification and 
Conversion 

■ String Comparison and 
Manipulation 

■ Searching and Sorting 

■ Time Routines 

■ File and Directory Manipulation 

■ Input and Output Routines 

■ System Calls 

■ Graphics Modes 

■ Drawing and Animation 

■ Combining Graphics and Text 

950 Pages, 772 x 9%, Softbound 
ISBN: 0-672-22631-6 

No. 22631, $24.95 


Turbo C Developer’s Library 

Edward R. Bought and Thomas D. Hoops 

Designed for the programmer and 
applications developer, this book 
contains a wealth of information to 
eliminate the dreary task of creat- 
ing all the background routines that 
make up a high-quality professional 
application. It is a comprehensive 
collection of high-performance rou- 
tines created by applications de- 
velopers. The routines allow the 
reader to concentrate on what the 
application will accomplish rather 
than on the tools needed to create 
it. 

This complete set of procedures 
and functions includes routines for 
menu management, data base de- 
velopment, data entry, printing, and 
many other areas that are used 
daily in applications development. 

Topics covered include: 

■ Introduction 

■ How to Use the Libraries 

■ How to Use the Routine 
Descriptions 

■ Hardware and Software 
Configurations 

■ Main Library Routines 

■ Btrieve File System Routines 

■ Novell Networking Routines 

■ Sample Applications and 
Utilities 

■ Appendices: Cross References, 
Keyboard Scan Code Table, 
Bibliography 

450 Pages, 772 x 9%, Softbound 
ISBN: 0-672-22642-1 

No. 22642, $24.95 


Visit your local book retailer, use the order form provided, or call 800-428-SAMS. 


To Order the Sample Programs Diskette 

As a convenience and learning aid, you may order a diskette containing the current version 
of all C program source code and header files listed in this book, as well as errata and late- 
breaking NetBIOS news. The source code files are shipped on an unsupported, as-is basis. 
Neither Howard W. Sams & Company nor Sacramento Distribution Service assumes any lia- 
bility with respect to the use, accuracy, or fitness of the information contained within the 
diskette. 

Send this form with payment to: 


Sacramento Distribution Service 
RO. Box 3014 

Sacramento, California 95611-3014 


Diskette Order Form 

Schwaderer, C Programmer's Guide to NetBIOS, #22638 


Name 

Company 



Address 

City 


State 

Country 


Zip 



Phone (for collect calls about order problems) ( ) 

Place of book Type of computer 

purchase used 


5 V4" Disks 360 KB (DOS 2.0 or higher) 

Quantity: @ ^^22.95 U.S. Total: $ 

3 Disks 720 KB (DOS 3.2 or higher) 

Quantity: @ $24.95 U.S. Total: $ 

California residents, add 6.5% 

Santa Clara County, CA residents, add 7% Tax: $ 


U.S. orders — $2.50 
Foreign orders — $4.00 


Shipping & 
Handling: $ 


Total Order 

Check or money order enclosed. Amount: $ 


Please allow six weeks for delivery within the U.S. 
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REFERENCE CARD 

®1988 by W. David Schwaderer 



HOWARD W. SAWS ^COMPANY 

A Division of Macmillan, Inc. 

4300 West 62nd Street 
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Commands Listed by Cathodes 


Command 

Command 

Code 

Retcode LSN 

Num Buffer® Length 

Call 

Name Name Rto 

Sto Post® 

Lana 

Num 

Reset 

32h 

O I 

General 

I 



I 

Adapter 

Status 

33h, B3h 

O 

I I 

I 

(*) 

C 

I 

Cancel 

35h 

o 

I 



I 

Unlink 

70h 

o 




I 


Add 

Name 

30h, BOh 

o 

o 

Name 

I 

C 

I 

Delete 

Name 

31h, Blh 

o 



I 

c 

I 

Add 

Group 

Name 

36h, B6h 

o 

o 


I 

c 

I 


Session 


Call 

lOh, 90h 

o 

o 



u 

0 

II 

Q 

0 

II 

Q 

I 

Listen 

11 h, 91 h 

o 

o 



I/C I D=0 D=0 C 

(*) 

C 

I 

Hang Up 

12h, 92h 

o 

I 



I 

Send 

I4h, 94h 

o 

I 

I 

I 

c 

I 

Receive 

15h, 95h 

o 

I 

I 

I/O 

c 

I 

Receive- 

l6h, 96h 

o 

o 

I/C I 

I/O 

c 

I 

Any 




(FFH) 




Chain 

Send 

17h, 97h 

o 

I 

I 

I 

I c 

I 

Session 

34h, B4h 

o 


I 

I/O 

I c 

I 

Status 






(*) 



Datagram 


Send 

Datagram 

20h, AOh 

O 

I 

I 

I 

I 

c 

I 

Receive 

Datagram 

21h, Alh 

O 

I 

(FFH) 

I 

I/O 

o 

c 

I 

Send 

Broadcast 

Datagram 

22h, A2h 

o 

I 

I 

I 


c 

I 

Receive 

Broadcast 

Datagram 

23h, A3h 

o 

I 

I 

I/O 

o 

c 

I 




Commands listed by Command Code 


Command 

Command 

Code 

Retcode 

LSN 

Num Buffer® Length 

Call 

Name 

Name 

Rto 

Sto 

Post® 

Lana 

Num 

Call 

lOh, 90h 

O 

o 



I 

I 

D=0 

D=0 

C 

I 

Listen 

llh, 91h 

O 

o 



I/C 

(*) 

I 

D=0 

D=0 

C 

I 

Hang Up 

12h, 92h 

o 

I 







C 

I 

Send 

I4h, 94h 

o 

I 

I 

I 





C 

I 

Receive 

15h, 95h 

o 

I 

I 

I/O 





C 

I 

Receive- 

Any 

I6h, 96h 

o 

o 

I/C I 

(FFH) 

I/O 





C 

I 

Chain 

Send 

17h, 97h 

o 

I 

I 

I 

I 




C 

I 

Send 

Datagram 

20h, AOh 

o 


1 I 

I 

I 




C 

I 

Receive 

Datagram 

21h, Alh 

o 


I I 

(FFH) 

I/O 

O 




C 

I 

Send 

Broadcast 

Datagram 

22h, A2h 

o 


I I 

I 





C 

I 

Receive 

Broadcast 

Datagram 

23h, A3h 

o 


I I 

I/O 

O 




C 

I 

Add 

Name 

30h, BOh 

o 


o 



I 



c 

I 

Delete 

Name 

31h, Blh 

o 





I 



c 

I 

Reset 

32h 

o 

I 

I 







I 

Adapter 

Status 

33h, B3h 

o 


I 

I 

I 

(*) 




c 

I 

Session 

Status 

34h, B4h 

o 


I 

I/O 


I 

(*) 



c 

I 

Cancel 

35h 

o 


I 







I 

Add 

Group 

Name 

36h, B6h 

o 


o 



I 



c 

I 

Unlink 

70h 

o 









I 

Send 

No-Ack 

71h, Flh 

o 

I 

I 

I 





c 

I 

Chain 

Send 

No-Ack 

72h, F2h 

o 

I 

I 

I 

I 




c 

I 


Legend: I Input, O Output, C Conditional 



The Neb Fields 


Offset 

Field Name 

Length 
in Bytes 

Field Structure 

+00 

Command 

1 

□ 

+01 

Return Code 

1 

□ 

+02 

Local Session Number 

1 

□ 

+03 

Name Number 

1 

□ 

+04 

Buffer Address 

4 

□□□□ 

+08 

Buffer Length 

2 

□□ 

+ 10 

Call Name 

16 

□□□□□□□□□□□□□□□□ 

+26 

Name (Local) 

16 

□□□□□□□□□□□□□□□□ 

+42 

Receive Time Out 

1 

□ 

+43 

Send Time Out 

1 

□ 

+44 

Post Routine Address 

4 

□□□□ 

+48 

LANA Number 

1 

□ 

+49 

Command Complete Flag 

1 

□ 

+ 50 

Reserved Field 

14 

□□□□□□□□□□□□□□ 



A C Neb Structure 


^define US6C unsigned char 
^define USGI unsigned 
^define US6L unsigned Long 

struct Neb 


USGC 

NebCommand; 

/* 

command code 

*/ 


USGC 

NebRetCode; 

/* 

return code 

*/ 


USGC 

NcbLsn; 

/* 

local session number 

*/ 


USGC 

NebNum; 

/* 

Datagram ADD NAME table entry 

*/ 


char 

* NebBufferOffset; 

/* 

I/O buffer offset 

*/ 


USGI 

NebBufferSegment; 

/* 

I/O buffer segment 

*/ 


USGI 

NcbLength; 

/★ 

length of data in I/O buffer 

*/ 


char 

NebCal lName[16] ; 

/* 

remote system name for CALL 

*/ 


char 

NcbNameC16] ; 

/* 

local adapter network name 

*/ 


USGC 

NebRto; 

/* 

receive timeouts in 1/2 second 

units 

*/ 

USGC 

NebSto; 

/* 

send timeouts in 1/2 second 

units 

*/ 

char 

* NebPostRtnOffset; 

/* 

offset of post routine 

*/ 


USGI 

NcbPostRtnSegment; 

/* 

segment of post routine 

*/ 



USGC NebLanaNum; /* network adapter number to execute cmd */ 

USGC NcbCmdCplt; /* OxFF ==> command pending, else cmplted */ 

char NebReservedAreaCH] ; /* work area for network card */ 

> ZeroNcb; /* prototype NCB for sizeof calcs */ 


A MASM Neb Structure 

; Neb Structure 

Neb struc 


Ncb_Command 

db 

OOh 

;Ncb 

Neb^RetCode 

db 

OOh 

;Ncb 

Ncb_Lsn 

db 

OOh 

;Ncb 

Ncb_Num 

db 

OOh 

;Ncb 

Ncb_BufferOf f 

dw 

OOOOh 

;Ncb 

Ncb_BufferSeg 

dw 

OOOOh 

;Ncb 

Ncb_Length 

dw 

OOOOh 

;Ncb 

Ncb_Cal IName 

db 

16 dup(O) 

;Ncb 

Ncb^Name 

db 

16 dup(O) 

;Ncb 

Ncb_Rto 

db 

OOh 

;Ncb 

Ncb_Sto 

db 

OOh 

;Ncb 

Ncb_PostOff 

dw 

OOOOh 

;Ncb 

Ncb_PostSeg 

dw 

OOOOh 

;Ncb 

Ncb_Lana_Num 

db 

OOh 

;Ncb 

Ncb_Cmd_Cplt 

db 

OOh 

;Ncb 

Ncb_Reserve 

db 

14 dup(O) 

;Ncb 

Neb ends 




command field 

return code 

Local session number 

name number from AddName 

message buffer offset 

message buffer segment 

message buffer length (in bytes) 

remote name 

AddName 

receive timeout 
send timeout 
post routine offset 
post routine segment 
adapter number 

OFFh ==> command pending indicator 
reserved area 



NetBIOS Final Return Codes 


OOh Successful completion, good return 

01 h Invalid buffer length 

03 h Invalid command 

05h Command timed-out 

06h Incomplete received message 

07h Local No-Ack command failed 

08h Invalid local session number 

09h No resource available 

OAh Session has been closed 

OBh Command was canceled 

ODh Duplicate name in local NetBIOS name table 

OEh NetBIOS name table full 

OFh Name has active sessions and is now deregistered 

11 h NetBIOS local session table full 

12h Session open rejected because no Listen is outstanding 

13h Illegal name number 

I4h Cannot find name called or no answer 

15h Name not found, or cannot specify asterisk (*) or OOh as first byte of NcbName, 

or the name is deregistered and cannot be used 
l6h Name in use on remote adapter 

17h Name deleted 

18h Session ended abnormally 

19h Name conflict detected 

lAh Incompatible remote device (PC Network) 

21h Interface busy 

22h Too many commands outstanding 

23h Invalid number in NcbLanaNum field 

24h Command completed while cancel occurring 

2 5h Reserved name specified for Add Group Name 

26h Command not valid to cancel 

3 Oh Name defined by another process (OS/2 Extended Edition only) 

34h NetBIOS environment not defined (OS/2 Extended Edition only) 

35h Required operating system resources (OS/2 Extended Edition only) 

36h Maximum applications exceeded (OS/2 Extended Edition only) 

37h No SAPs available for NetBIOS (OS/2 Extended Edition only) 

38h Requested resources not available (OS/2 Extended Edition only) 

40h System error (PC Network) 

41 h Hot carrier from a remote adapter detected (PC Network) 

42h Hot carrier from this adapter detected (PC Network) 

43h No carrier detected (PC Network) 

4Eh Status bit 12, 14, or 15 on longer than one minute (Token-Ring) 

4Fh One or more of status bits 8-11 on (Token-Ring) 

50h-F6h Adapter malfunction 

F7h Error on implicit DIR. INITIALIZE 

F8h Error on implicit DIR.OPEN.ADAPTER 

F9h IBM LAN Support Program internal error 

FAh Adapter check 

FBh NetBIOS program not loaded in PC 

FCh DIR.OPEN.ADAPTER or DLC. OPEN. SAP failed — check parameters 

FDh Unexpected adapter close 

FFh Command-pending status 
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NetBIOS (Network Basic Input/Output System) is a pervasive Local Area Network 
(LAN) communications programming interface. Its many implementations sup- 
port a spectrum of operating environments, including PC-DOS™ OS/2™ UNIX® , 
the IBM® Token-Ring Network, Ethernet™, IEEE 802.2 LLC, XNS, and TCP/IP, to 
name a few. This prolific NetBIOS availability within virtually every significant 
LAN environment has propelled it to the status of a de facto industry standard. 

Mastering NetBIOS provides you with a highly marketable, leading-edge skill 
within the exploding LAN communications market. To enable you to understand 
how to harness the blistering capabilities of LANs, you'll discover within these 
pages: 

• what NetBIOS is, where it came from, and how it is related to other 
LAN hardware and software 

• the essentials and intricacies of NetBIOS session, datagram, and name 
programming as illustrated by insightful Microsoft® C 5.0 sample 
programs available on diskette for experimentation 

• a discussion of LAN data security and integrity, including a treatise on 
high performance Cyclic Redundancy Check (CRC) programming 

• a NetBIOS technical reference and tear-out reference card 

"... a comprehensive survey of NetBIOS concepts and practices backed by 
thorough program examples. . a useful reference in any network 
communication library. " 

Leo J. Esposito 

Systems Manager for Local Area Networks 
IBM Corporation 

W. David Schwaderer is an internationally recognized authority on data com- 
munications, including LANs. He is the author of five data communications prod- 
ucts sold by IBM and three books on data communications and C programming. 
David is currently a senior programmer in IBM's San Jose Storage Systems 
Strategy and Architecture Department, where his primary activities involve high 
performance data communications exploitation. 
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